Some refactoring and docstring updates.

utils/generate_markdown_docs.py

 
 
 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:
 
 
 def remove_trailing_whitespace(filename):
-    nchanged = 0
+    """
+    Removes trailing whitespace from a file.
+
+    :param filename: The name of the file to process
+    :type str:
+    """
+    num_changed = 0
+    # open the source file
-        code1 = f.read().decode()
-    lines = [line.rstrip() for line in code1.splitlines()]
+        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
-    lines.append("")  # always end with a newline
-    code2 = "\n".join(lines)
-    if code1 != code2:
-        nchanged += 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
-            f.write(code2.encode())
+            f.write(destination_file.encode())
+    """
+    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()