experiments in generated API nav files.

Author: carl-adams-planet

docs/api-planet-auth-utils.md renamed to docs/api-planet-auth-utils.md.retired

@@ -0,0 +1,38 @@
+"""Generate the code reference pages."""
+
+# Recipe to break up API docs into multiple pages from
+# https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+api_nav = mkdocs_gen_files.Nav()
+
+repo_root = Path(__file__).parent.parent.parent
+src = repo_root / "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("gen_reference", doc_path)
+
+    parts = tuple(module_path.parts)
+
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+    elif parts[-1] == "__main__":
+        continue
+
+    api_nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print("::: " + identifier, file=fd)
+        # TODO: add the options I want.  See my old manual api*.md files.
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(repo_root))
+
+
+with mkdocs_gen_files.open("gen_reference/API_NAV.md", "w") as nav_file:
+    nav_file.writelines(api_nav.build_literate_nav())

docs/api-planet-auth.md renamed to docs/api-planet-auth.md.retired

@@ -44,6 +44,11 @@ hooks:
 
 plugins:
   - search:
+  - gen-files:
+      scripts:
+        - docs/scripts/gen_api_pages.py
+  - literate-nav:
+      nav_file: 'API_NAV.md'
   - macros:
       include_dir: 'docs/examples'
       on_error_fail: true
@@ -77,9 +82,10 @@ nav:
     - Overview: 'library-overview.md'
     - Auth Client Configuration: 'configuration.md'
     - Built-in Injection: 'built-ins.md'
-  - API Reference:
-    - Planet Auth: 'api-planet-auth.md'
-    - Planet Auth Utils: 'api-planet-auth-utils.md'
+  # - API Reference:
+  #   - Planet Auth: 'api-planet-auth.md'
+  #   - Planet Auth Utils: 'api-planet-auth-utils.md'
+  - API Reference: gen_reference/
   - Examples:
     - Installation: 'examples-installation.md'
     - CLI: 'examples-cli.md'

docs/scripts/gen_api_pages.py

@@ -48,10 +48,11 @@ docs = [
     #   https://github.com/mkdocstrings/mkdocstrings/discussions/743
     "mkdocstrings[python] == 0.28.3",
     "mkdocs-click",
+    "mkdocs-gen-files",
+    "mkdocs-literate-nav",
+    "mkdocs-linkcheck",
     "mkdocs-material == 9.6.12",  # Upgrades may interact with docs/custom_theme
     "mkdocs-macros-plugin",
-    "mkdocs-linkcheck",
-    # "linkcheckmd",
 ]
 examples = [
     "flask",