From 26b2d4af5cace3adccd2133fd8b1813d566ef478 Mon Sep 17 00:00:00 2001
From: Philippe Leprince <philippe@ynput.io>
Date: Thu, 13 Mar 2025 15:39:48 +0100
Subject: [PATCH] add docstrings to mkdocs_hooks.py

Signed-off-by: Philippe Leprince <philippe@ynput.io>
---
 mkdocs_hooks.py | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/mkdocs_hooks.py b/mkdocs_hooks.py
index a2d803cdc2..af4b18bb11 100644
--- a/mkdocs_hooks.py
+++ b/mkdocs_hooks.py
@@ -5,7 +5,19 @@ import json
 
 TMP_FILE = "./missing_init_files.json"
 
+
 def add_missing_init_files(*roots):
+    """
+    This function takes in one or more root directories as arguments and scans
+    them for Python files without an `__init__.py` file. It generates a JSON
+    file named `missing_init_files.json` containing the paths of these files.
+
+    Args:
+        *roots: Variable number of root directories to scan.
+
+    Returns:
+        None
+    """
     nfiles = []
 
     for root in roots:
@@ -17,7 +29,7 @@ def add_missing_init_files(*roots):
                 nfiles.append(f"{dirpath}/__init__.py")
                 sys.stdout.write(
                     "\r\x1b[K" + f"PRE-BUILD: created {len(nfiles)} "
-                    "temp __init__.py files"
+                    "temp '__init__.py' files"
                 )
                 sys.stdout.flush()
 
@@ -29,6 +41,17 @@ def add_missing_init_files(*roots):
 
 
 def remove_missing_init_files():
+    """
+    This function removes temporary `__init__.py` files created in the
+    `add_missing_init_files()` function. It reads the paths of these files from
+    a JSON file named `missing_init_files.json`.
+
+    Args:
+        None
+
+    Returns:
+        None
+    """
     with open(TMP_FILE, "r") as f:
         nfiles = json.load(f)
 
@@ -36,7 +59,7 @@ def remove_missing_init_files():
         Path(file).unlink()
         sys.stdout.write(
             "\r\x1b[K" + f"POST_BUILD: removed {len(nfiles)} "
-            "temp __init__.py files"
+            "temp '__init__.py' files"
         )
         sys.stdout.flush()
 
@@ -47,8 +70,18 @@ def remove_missing_init_files():
 
 
 def on_pre_build(config):
+    """
+    This function is called before the MkDocs build process begins. It adds
+    temporary `__init__.py` files to directories that do not contain one, to
+    make sure mkdocs doesn't ignore them.
+    """
     add_missing_init_files("client", "server", "tests")
 
 
 def on_post_build(config):
+    """
+    This function is called after the MkDocs build process ends. It removes
+    temporary `__init__.py` files that were added in the `on_pre_build()`
+    function.
+    """
     remove_missing_init_files()