[API Documentation] Cover more submodules

docs/generate_api_doc_pages.py

@@ -1,50 +1,63 @@
-import shutil
 import inspect
-import sys
 from logging import getLogger
 from pathlib import Path
 
 import webknossos
 
-'''
+"""
 This script generates a mapping of all classes in webknossos to their
 corresponding MkDocs pages. It is used to generate the API reference.
-'''
+"""
 
 logger = getLogger(__name__)
 
 OUT_PATH = Path("src/api")
 
-for key, value in webknossos.__dict__.items():
-    if getattr(value, "__module__", "").startswith("webknossos"):
-
-        logger.debug("Processing module", key)
-
-        module = value.__module__
-
-        module_parts = module.split('.')
-        module_name = module_parts[-1]
-        module_path = "/".join(module_parts[:-1])
-        file_name = f"{key.lower()}.md"
-
-        # Extract all classes from the module
-        classes = inspect.getmembers(sys.modules[module], inspect.isclass)
-
-        # Only include classes that are in implemented in that module
-        classes = [c for c in classes if c[1].__module__ == module]
-        classes = [c for c in classes if not c[0].startswith("_")]
-
-        # The file content uses a special syntax for MkDocs to render the
-        # docstrings as Markdown. The syntax is:
-        # ::: module.submodule.class
-        # See https://mkdocstrings.github.io/python/
-        classes_string = "\n".join([f"            - {c[0]}" for c in classes])
-        file_content = f"""::: {module}
+# Initialize a dictionary to store submodules and their classes
+submodules_classes = {}
+
+# Iterate through all the members of the module
+for name, member in inspect.getmembers(webknossos):
+    # Check if the member is a module (submodule)
+    if inspect.ismodule(member) and member.__name__.startswith("webknossos"):
+        submodule_name = member.__name__
+
+        # List classes in the submodule
+        classes = inspect.getmembers(member, inspect.isclass)
+
+        # Filter classes that are defined in this specific submodule
+        defined_classes = [
+            cls for cls_name, cls in classes if cls.__module__ == submodule_name
+        ]
+
+        # If there are classes defined in this submodule, add them to the dictionary
+        if defined_classes:
+            submodules_classes[submodule_name] = defined_classes
+
+# Print the submodules and their classes
+for submodule, classes in submodules_classes.items():
+    # The file content uses a special syntax for MkDocs to render the
+    # docstrings as Markdown. The syntax is:
+    # ::: module.submodule.class
+    # See https://mkdocstrings.github.io/python/
+    classes_string = "\n".join(
+        [
+            f"            - {c.__name__}"
+            for c in classes
+            if not c.__name__.startswith("_")
+        ]
+    )
+    file_content = f"""::: {submodule}
     options:
         members:\n{classes_string}\n"""
-
-        out_path=OUT_PATH.joinpath(module_path)
-        out_path.mkdir(exist_ok=True, parents=True)
 
-        logger.debug(f"Writing API docs to {out_path.joinpath(file_name)}")
-        out_path.joinpath(file_name).write_text(file_content)
+    submodule_parts = submodule.split(".")
+    submodule_name = submodule_parts[-1]
+    file_name = Path(f"{submodule_name}.md")
+    file_path = "/".join(submodule_parts[:-1])
+
+    out_path = OUT_PATH.joinpath(file_path)
+    out_path.mkdir(exist_ok=True, parents=True)
+
+    logger.debug(f"Writing API docs to {out_path.joinpath(file_name)}")
+    out_path.joinpath(file_name).write_text(file_content)

docs/mkdocs.yml

@@ -115,23 +115,23 @@ nav:
       - API Reference:
           - Overview: api/webknossos.md
           - Geometry:
-              - BoundingBox: api/webknossos/geometry/boundingbox.md
-              - NDBoundingBox: api/webknossos/geometry/ndboundingbox.md
+              - BoundingBox: api/webknossos/geometry/bounding_box.md
+              - NDBoundingBox: api/webknossos/geometry/nd_bounding_box.md
               - Mag: api/webknossos/geometry/mag.md
-              - Vec3Int: api/webknossos/geometry/vec3int.md
-              - VecInt: api/webknossos/geometry/vecint.md
+              - Vec3Int: api/webknossos/geometry/vec3_int.md
+              - VecInt: api/webknossos/geometry/vec_int.md
           - Dataset:
               - Dataset: api/webknossos/dataset/dataset.md
               - Layer: api/webknossos/dataset/layer.md
-              - MagView: api/webknossos/dataset/magview.md
+              - MagView: api/webknossos/dataset/mag_view.md
               - View: api/webknossos/dataset/view.md
           - Annotation: api/webknossos/annotation/annotation.md
           - Skeleton:
               - Skeleton: api/webknossos/skeleton/skeleton.md
               - Group: api/webknossos/skeleton/group.md
               - Tree: api/webknossos/skeleton/tree.md
               - Node: api/webknossos/skeleton/node.md
-          - Authentication & Server Context: api/webknossos/client/webknossos_context.md
+          - Authentication & Server Context: api/webknossos/client/context.md
           - Administration:
               - User: api/webknossos/administration/user.md
               - Project: api/webknossos/administration/project.md
@@ -174,7 +174,7 @@ plugins:
                     show_source: false
                     docstring_style: null
                     docstring_section_style: list
-                    heading_level: 2
+                    heading_level: 1
                     inherited_members: true
                     merge_init_into_class: true
                     parameter_headings: true