docs: Properly sort modules when building the API documentation (#231)

CHANGELOG.md

@@ -36,6 +36,10 @@ Things to be included in the next release go here.
 - Renamed some of the abstract base classes to separate them from the actual device driver classes.
 - Updated the documentation templates to use the new jinja template style that `mkdocstrings-python` is switching to.
 
+### Fixed
+
+- Fixed the API documentation to properly sort all the modules so that the Table of Contents is readable.
+
 ---
 
 ## v1.4.2 (2024-05-09)

docs/generate_api_pages.py

@@ -1,6 +1,7 @@
 """Generate the code reference pages and navigation."""
 
 from pathlib import Path
+from typing import Tuple
 
 import mkdocs_gen_files
 
@@ -11,7 +12,27 @@
 root = Path(__file__).parent.parent
 src = root / "src"
 
-for path in src.rglob("*.py"):
+
+def sort_paths(path_object: Path) -> Tuple[int, str]:
+    """A helper function to provide a way to sort a list of Path objects.
+
+    This allows for sorting based on the name, but places modules above subpackages.
+
+    Args:
+        path_object: A Path object representing a Python module.
+
+    Returns:
+        The key to use in the sorting method/function.
+    """
+    # Count the number of parts in the path minus 1 (to ignore the file itself)
+    # This effectively gives us the "depth" of the file
+    depth = len(path_object.parts) - 1
+    # Sort by depth first, then alphabetically
+    return depth, path_object.as_posix().lower()
+
+
+file_list = sorted(src.rglob("*.py"), key=sort_paths)
+for path in file_list:
     module_path = path.relative_to(src).with_suffix("")
     doc_path = path.relative_to(src).with_suffix(".md")
     full_doc_path = Path("reference", doc_path)
@@ -42,24 +63,24 @@
             ("helpers", "enums"),
             ("helpers", "__init__"),
         }:
-            fd.write("    options:\n      show_if_no_docstring: true\n")
+            fd.write("    options:\n        show_if_no_docstring: true\n")
         if module_path.parts[-2:] == ("commands", "__init__"):
             fd.write(
                 "    options:\n"
-                "      inherited_members: false\n"
-                "      filters: ['!^_', '^__init__', '^gen_']\n"
-                "      members_order: source\n"
-                "      merge_init_into_class: false\n"
+                "        inherited_members: false\n"
+                "        filters: ['!^_', '^__init__', '^gen_']\n"
+                "        members_order: source\n"
+                "        merge_init_into_class: false\n"
             )
         elif module_path.parts[1] == "commands":
             fd.write(
                 "    options:\n"
-                "      inherited_members: false\n"
-                "      merge_init_into_class: false\n"
-                "      filters: ['!^_']\n"
+                "        inherited_members: false\n"
+                "        merge_init_into_class: false\n"
+                "        filters: ['!^_']\n"
             )
         if module_path.parts[-2:] == ("drivers", "__init__"):
-            fd.write("    options:\n      members_order: source\n\n")
+            fd.write("    options:\n        members_order: source\n\n")
 
     mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))