Merge pull request #13 from HazyResearch/feat/auto-gen-api-reference

feat: add auto-generated API reference via gen-files + literate-nav

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())

mkdocs.yml

@@ -50,6 +50,11 @@ extra_css:
 
 plugins:
   - search
+  - gen-files:
+      scripts:
+        - docs/gen_ref_pages.py
+  - literate-nav:
+      nav_file: SUMMARY.md
   - mkdocstrings:
       default_handler: python
       handlers:
@@ -152,23 +157,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

pyproject.toml

@@ -85,6 +85,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]