Include auto-generated code docs

build-docs.sh

@@ -5,6 +5,6 @@ set -o nounset
 export OSS_PARAMS_FILENAME=gso/oss-params-example.json
 export TESTING=true
 
-pip install mkdocstrings-python mkdocs_gen_files mkdocs-material mkdocs-literate-nav mkdocs-section-index
+pip install mkdocstrings-python mkdocs_gen_files mkdocs-material mkdocs-literate-nav mkdocs-redirects
 
 mkdocs build

docs/scripts/gen_ref_pages.py

@@ -7,32 +7,29 @@ from pathlib import Path
 
 import mkdocs_gen_files
 
-nav = mkdocs_gen_files.Nav()
-
-root = Path(__file__).parent.parent
+root = Path(__file__).parent.parent.parent
 src = root / "gso"
+ignored_modules = ["db", "graphql_api", "main", "migrations"]
 
 for path in sorted(src.rglob("*.py")):
-    module_path = path.relative_to(src).with_suffix("")
-    doc_path = path.relative_to(src).with_suffix(".md")
+    module_path = path.relative_to(root).with_suffix("")
+    doc_path = path.relative_to(root).with_suffix(".md")
     full_doc_path = Path("reference", doc_path)
 
     parts = tuple(module_path.parts)
 
-    if parts[-1] == "__init__":
+    if any(module in parts for module in ignored_modules):
+        #  E.g. ignore generated migration files from SQLAlchemy.
+        continue
+    elif 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:
         identifier = ".".join(parts)
         print("::: " + identifier, file=fd)
 
     mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root))
-
-with mkdocs_gen_files.open("reference/SUMMARY.md", "w") as nav_file:
-    nav_file.writelines(nav.build_literate_nav())

mkdocs.yml

@@ -51,7 +51,6 @@ plugins:
         - docs/scripts/gen_ref_pages.py
   - literate-nav:
       nav_file: SUMMARY.md
-  - section-index
   - mkdocstrings
 
 # Page tree
@@ -86,7 +85,7 @@ nav:
       - Netbox: admin_guide/oss_bss/netbox.md
       - LibreNMS: admin_guide/oss_bss/librenms.md
       - Kentik: admin_guide/oss_bss/kentik.md
-  - Code Documentation: reference/
+  - Code Documentation: reference/gso/
 
 # Extensions
 markdown_extensions: