From 0fb7bf8dd941317e5aea448aed06b9f2652e96af Mon Sep 17 00:00:00 2001
From: Jon Saad-Falcon <jonsaadfalcon@gmail.com>
Date: Thu, 5 Mar 2026 20:52:15 +0000
Subject: [PATCH] feat: add auto-generated API reference via gen-files +
 literate-nav

- Add gen-files and literate-nav mkdocs plugins
- Create docs/gen_ref_pages.py (adapted from IPW) to auto-generate API reference pages
- Replace 15 manual API nav entries with single auto-generated api-reference/ section
- Add mkdocs-gen-files and mkdocs-literate-nav to docs extra dependencies

Cross-pollinated from intelligence-per-watt docs patterns.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 docs/gen_ref_pages.py | 31 +++++++++++++++++++++++++++++++
 mkdocs.yml            | 23 ++++++-----------------
 pyproject.toml        |  2 ++
 3 files changed, 39 insertions(+), 17 deletions(-)
 create mode 100644 docs/gen_ref_pages.py

diff --git a/docs/gen_ref_pages.py b/docs/gen_ref_pages.py
new file mode 100644
index 00000000..cd185750
--- /dev/null
+++ b/docs/gen_ref_pages.py
@@ -0,0 +1,31 @@
+"""Generate the code reference pages."""
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()
+src = Path("src")
+
+for path in sorted(src.rglob("*.py")):
+    module_path = path.relative_to(src).with_suffix("")
+    doc_path = path.relative_to(src).with_suffix(".md")
+    full_doc_path = Path("api-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].startswith("_"):
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        fd.write(f"::: {identifier}")
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path)
+
+with mkdocs_gen_files.open("api-reference/SUMMARY.md", "w") as nav_file:
+    nav_file.writelines(nav.build_literate_nav())
diff --git a/mkdocs.yml b/mkdocs.yml
index 80650f1c..57c7374a 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -44,6 +44,11 @@ theme:
 
 plugins:
   - search
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -145,23 +150,7 @@ nav:
       - Design Principles: architecture/design-principles.md
       - Security: architecture/security.md
       - Channels: architecture/channels.md
-  - API Reference:
-      - api/index.md
-      - SDK (Jarvis): api/sdk.md
-      - Core: api/core.md
-      - Engine: api/engine.md
-      - Agents: api/agents.md
-      - Memory: api/memory.md
-      - Tools: api/tools.md
-      - Intelligence: api/intelligence.md
-      - Learning: api/learning.md
-      - Traces: api/traces.md
-      - Telemetry: api/telemetry.md
-      - Benchmarks: api/bench.md
-      - Evals: api/evals.md
-      - Server: api/server.md
-      - Security: api/security.md
-      - Channels: api/channels.md
+  - API Reference: api-reference/
   - Deployment:
       - Docker: deployment/docker.md
       - systemd (Linux): deployment/systemd.md
diff --git a/pyproject.toml b/pyproject.toml
index 18de6422..b928c5a1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -84,6 +84,8 @@ docs = [
     "mkdocs>=1.6",
     "mkdocs-material>=9.5",
     "mkdocstrings[python]>=0.25",
+    "mkdocs-gen-files>=0.5",
+    "mkdocs-literate-nav>=0.6",
 ]
 
 [project.scripts]