File size: 3,358 Bytes
21e7376 |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 |
#!/usr/bin/env python3
import os
import subprocess
import sys
import yaml
import argparse
import hashlib
# pydoc-markdown -I . -m module_name --render_toc > doc.md
def hash_file(filename):
"""
Calculate the md5 hash of a file. Used to check for stale files.
:param filename: The name of the file to check
:type str:
:return: A string containing the md5 hash of the file
:rtype: str
"""
if os.path.exists(filename):
hasher = hashlib.md5()
with open(filename, "rb") as file_to_hash:
buffer = file_to_hash.read()
hasher.update(buffer)
return hasher.hexdigest()
else:
return 0
def remove_trailing_whitespace(filename):
"""
Removes trailing whitespace from a file.
:param filename: The name of the file to process
:type str:
"""
num_changed = 0
# open the source file
with open(filename, "rb") as f:
source_file = f.read().decode()
# grab all the lines, removing the trailing whitespace
lines = [line.rstrip() for line in source_file.splitlines()]
# process lines to construct destination file
while lines and not lines[-1]:
lines.pop(-1)
lines.append("")
destination_file = "\n".join(lines)
# compare source and destination and write only if changed
if source_file != destination_file:
num_changed += 1
with open(filename, "wb") as f:
f.write(destination_file.encode())
if __name__ == "__main__":
"""
Pre-commit hook to generate Python API documentation using pydoc-markdown
and write as markdown files. Each package should have a config file,
pydoc-config.yaml, at the root level that provides configurations for
the generation. Fails if documentation was updated, passes otherwise. This
allows for pre-commit to fail in CI/CD and makes sure dev commits the doc
updates.
"""
parser = argparse.ArgumentParser()
parser.add_argument("--package_dirs", nargs="+")
args = parser.parse_args()
ok = True
for package_dir in args.package_dirs:
config_path = os.path.join(os.getcwd(), package_dir, "pydoc-config.yaml")
print(config_path)
with open(config_path) as config_file:
config = yaml.full_load(config_file)
for module in config["modules"]:
module_name = module["name"]
submodules = module["submodules"]
output_file_name = f"./{config['folder']}/{module['file_name']}"
old_hash = hash_file(output_file_name)
module_args = []
for submodule in submodules:
module_args.append("-m")
module_args.append(f"{module_name}.{submodule}")
with open(output_file_name, "w") as output_file:
subprocess_args = [
"pydoc-markdown",
"-I",
f"./{package_dir}",
*module_args,
"--render-toc",
]
subprocess.check_call(subprocess_args, stdout=output_file)
remove_trailing_whitespace(output_file_name)
new_hash = hash_file(output_file_name)
ok &= old_hash == new_hash
sys.exit(0 if ok else 1)
|