From 49d22a3417d5a4932a2e5f6cbd613dbe4d2779fa Mon Sep 17 00:00:00 2001
From: Karel van Klink <karel.vanklink@geant.org>
Date: Thu, 28 Nov 2024 16:27:19 +0100
Subject: [PATCH] Include auto-generated code docs
---
build-docs.sh | 2 +-
docs/scripts/gen_ref_pages.py | 19 ++++++++-----------
mkdocs.yml | 3 +--
3 files changed, 10 insertions(+), 14 deletions(-)
diff --git a/build-docs.sh b/build-docs.sh
index e57c78c7..f9ffac0c 100755
--- a/build-docs.sh
+++ b/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
diff --git a/docs/scripts/gen_ref_pages.py b/docs/scripts/gen_ref_pages.py
index 06843d7d..9d0cd44d 100644
--- a/docs/scripts/gen_ref_pages.py
+++ b/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())
diff --git a/mkdocs.yml b/mkdocs.yml
index 28cdc0a5..a90ca43f 100644
--- a/mkdocs.yml
+++ b/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:
--
GitLab