docs: add automatic code reference generation (#285)

* docs: add automatic code reference generation

* fix: fix workflow with new mkdocs plugins

---------

Co-authored-by: pommedeterresautee <[email protected]>

Author: jonathlela

.github/workflows/deploy-static-site.yml

@@ -38,7 +38,7 @@ jobs:
           path: .cache
       - run: sudo apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
       - run: sudo apt-get install pngquant
-      - run: pip install git+https://${{secrets.GH_TOKEN}}@github.com/squidfunk/[email protected] "mkdocstrings[python]"
+      - run: pip install git+https://${{secrets.GH_TOKEN}}@github.com/squidfunk/[email protected] "mkdocstrings[python]"  mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index
       - run: pip install mkdocs-glightbox
       - run: pip install pillow cairosvg
       - run: mkdocs build

Dockerfile

@@ -40,7 +40,6 @@ COPY ./setup.py ./setup.py
 COPY ./setup.cfg ./setup.cfg
 COPY ./requirements.txt ./requirements.txt
 COPY ./README.md ./README.md
-COPY ./src/__init__.py ./src/__init__.py
 COPY ./src/kernl/__init__.py ./src/kernl/__init__.py
 
 

docs/Dockerfile.mkdocstrings

@@ -6,4 +6,4 @@ RUN pip install --no-cache-dir \
 
 # mkdocstrings plugin
 RUN pip install --no-cache-dir \
-  pip install mkdocstrings[python]
+  pip install mkdocstrings[python] mkdocs-gen-files mkdocs-literate-nav mkdocs-section-index

docs/gen_ref_pages.py

@@ -0,0 +1,38 @@
+"""Generate the code reference pages and navigation."""
+
+import os
+import sys
+from pathlib import Path
+
+import mkdocs_gen_files
+
+
+# Add the kernl module to python path
+sys.path.append(os.path.join(os.path.dirname(__file__), "..", "src"))
+
+nav = mkdocs_gen_files.Nav()
+
+for path in sorted(Path("src").rglob("*.py")):
+    module_path = path.relative_to("src").with_suffix("")
+    doc_path = path.relative_to("src").with_suffix(".md")
+    full_doc_path = Path("reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+        doc_path = doc_path.with_name("index.md")
+        full_doc_path = full_doc_path.with_name("index.md")
+    elif parts[-1] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("reference/SUMMARY.txt", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())

docs/reference/extended_matcher.md

@@ -139,6 +139,11 @@ markdown_extensions:
 # Plugins
 plugins:
   - search
+  - gen-files:
+      scripts:
+      - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.txt
   - typeset       # preserves html formatting in the navigation and t.o.c
   - glightbox     # image zoom functionality plugin
 
@@ -160,6 +165,7 @@ plugins:
         python:
           options:
             show_source: false
+
 watch:
   - src/kernl
 
@@ -171,9 +177,8 @@ nav:
       - How to support a new model: how-to-guides/support-new-model.md
 #  - Tutorials:
 #      - Page 1: tutorials/page.md
-  - Code Reference:
-      - Model Optimization: reference/model_optimization.md
-      - Graph Pattern Matching: reference/extended_matcher.md
+  # defer to gen-files + literate-nav
+  - Code Reference: reference/
   - Contribution guide:
       - Contributing: contribution-guide/contributing.md
       - Code of conduct: contribution-guide/code-of-conduct.md