Generate API reference automatically

pixano · Nov 15, 2023 · 1b59bfc · 1b59bfc
1 parent 1798b65
commit 1b59bfc
Show file tree

Hide file tree

Showing 10 changed files with 61 additions and 21 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,10 @@ All notable changes to Pixano will be documented in this file.
 
 - Add GitHub actions to format Python, UI, and Markdown code
 
+### Changed
+
+- Generate API reference automatically
+
 ## [0.2.1] - 2023-11-13
 
 ### Added

diff --git a/docs/code/index.md b/docs/code/index.md
@@ -5,3 +5,4 @@ Here you will find the documentation for all of our implemented models.
 - The **_pytorch_models_** module contains models from the PyTorch library.
 - The **_segment_anything_** module contains the Segment Anything Model (SAM) for Meta.
 - The **_tensorflow_models_** module contains models from the TensorFlow library.
+- The **_transformers_** module contains models from the Hugging Face Transformers library.
diff --git a/docs/code/pytorch_models/deeplabv3.md b/docs/code/pytorch_models/deeplabv3.md
diff --git a/docs/code/pytorch_models/maskrcnnv2.md b/docs/code/pytorch_models/maskrcnnv2.md
diff --git a/docs/code/pytorch_models/yolov5.md b/docs/code/pytorch_models/yolov5.md
diff --git a/docs/code/segment_anything/segment_anything.md b/docs/code/segment_anything/segment_anything.md
diff --git a/docs/code/tensorflow_models/efficientdet.md b/docs/code/tensorflow_models/efficientdet.md
diff --git a/docs/code/tensorflow_models/fasterrcnn.md b/docs/code/tensorflow_models/fasterrcnn.md
diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
@@ -0,0 +1,49 @@
+"""Generate the code API reference pages
+
+Refer to https://mkdocstrings.github.io/recipes/ for more details.
+"""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+SRC_PATH = "pixano_inference"
+REF_PATH = "code"
+IGNORED_FILES = ["__init__.py", "__version__.py"]
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path(SRC_PATH).rglob("*.py")):
+    module_path = path.relative_to(SRC_PATH).with_suffix("")
+    doc_path = path.relative_to(SRC_PATH).with_suffix(".md")
+    full_doc_path = Path(REF_PATH, doc_path)
+
+    parts = list(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    elif parts[-1] == "__main__":
+        continue
+
+    # Create root index file
+    if not parts:
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+        nav["index"] = doc_path.as_posix()
+        with open(f"docs/{REF_PATH}/index.md", "r") as index_file:
+            lines = index_file.readlines()
+            with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+                fd.writelines(lines)
+        mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+    # Add all python files that are not in the ignore list
+    elif not any(ignored in path.name for ignored in IGNORED_FILES):
+        nav[parts] = doc_path.as_posix()
+        with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+            identifier = ".".join(parts)
+            print("::: " + identifier, file=fd)
+        mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+
+with mkdocs_gen_files.open(f"{REF_PATH}/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -48,6 +48,11 @@ extra:
 plugins:
   - search
   - autorefs
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
   - mkdocstrings:
       handlers:
         python:
@@ -58,7 +63,7 @@ plugins:
             - https://pandas.pydata.org/pandas-docs/version/1.5/objects.inv
             - https://pillow.readthedocs.io/en/stable/objects.inv
             - https://arrow.apache.org/docs/objects.inv
-            - https://docs.pydantic.dev/2.0/objects.inv # no objects.inv available for 1.10
+            - https://docs.pydantic.dev/2.4/objects.inv
             - https://ipython.readthedocs.io/en/8.13.2/objects.inv
             - https://pytorch.org/docs/master/objects.inv
           options:
@@ -83,19 +88,6 @@ nav:
       - "Pre-annotation": user/pre_annotation.md
       - "Interactive annotation": user/interactive_annotation.md
 
-  - "API reference":
-      - code/index.md
-
-      - "pytorch_models":
-          - "DeepLabV3": code/pytorch_models/deeplabv3.md
-          - "MaskRCNNv2": code/pytorch_models/maskrcnnv2.md
-          - "YOLOv5": code/pytorch_models/yolov5.md
-
-      - "segment_anything":
-          - "SAM": code/segment_anything/segment_anything.md
-
-      - "tensorflow_models":
-          - "EfficientDet": code/tensorflow_models/efficientdet.md
-          - "FasterRCNN": code/tensorflow_models/fasterrcnn.md
+  - "API reference": code/
 
   - "Pixano": https://pixano.github.io