Feature/auto doc generation

{{cookiecutter.project_slug}}/.github/alternative_workflows/build_docs.yml

@@ -0,0 +1,21 @@
+name: Build and Deploy Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+{% raw %}
+jobs:
+  build-and-deploy-docs:
+    if: ${{ github.event.pull_request.merged }} or ${{ github.event_name == 'workflow_dispatch' }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          token: ${{ secrets.GH_TOKEN }}
+      - uses: ./.github/actions/python-poetry-env
+      - name: Deploy docs
+        run: poetry run mkdocs gh-deploy --force{% endraw %}

{{cookiecutter.project_slug}}/mkdocs.yml

@@ -14,9 +14,9 @@ theme:
         name: Switch to light mode
 
 nav:
-  - Introduction: 'index.md'
-  - api_docs.md
-  - changelog.md
+  - Home: 'index.md'
+  - Code Reference: reference/
+  - Changelog: changelog.md
 
 watch:
   - src/{{ cookiecutter.package_name }}
@@ -61,6 +61,12 @@ markdown_extensions:
 plugins:
   - table-reader
   - search
+  - gen-files:
+      scripts:
+        - scripts/gen_ref_pages.py
+  - literate-nav:
+      nav_vile: SUMMARY.md
+  - section-index
   - mkdocstrings:
       default_handler: python
       handlers:

{{cookiecutter.project_slug}}/pyproject.toml

@@ -37,6 +37,9 @@ click = "*"
 mkdocstrings = {version = ">=0.23", extras = ["python"]}
 mkdocs-material = "*"
 mkdocs-table-reader-plugin = "*"
+mkdocs-gen-files = "^0.5.0"
+mkdocs-literate-nav = "^0.6.1"
+mkdocs-section-index = "^0.3.9"
 mypy = "*"
 pre-commit = "*"
 pymdown-extensions = "*"
@@ -78,6 +81,9 @@ ignore = [
     "ARG",      # "Unused function argument". Fixtures are often unused.
     "S105",     # "Possible hardcoded password".
 ]
+"scripts/**" = [
+    "INP001",   # "Scripts are not part of a package."
+]
 
 [tool.ruff.lint.mccabe]
 max-complexity = 10

{{cookiecutter.project_slug}}/scripts/gen_ref_pages.py

@@ -0,0 +1,35 @@
+"""Generate the code reference pages and navigation."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+nav = mkdocs_gen_files.Nav()  # type: ignore[attr-defined, no-untyped-call]
+
+root = Path(__file__).parent.parent
+src = 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("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] == "__main__":
+        continue
+
+    nav[parts] = doc_path.as_posix()
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        ident = ".".join(parts)
+        fd.write(f"::: {ident}")
+
+    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())