chore: update project structure to 8e2aaf58

Author: collijk

.cruft.json

@@ -1,6 +1,6 @@
 {
   "template": "https://github.com/collijk/python-package-cookiecutter",
-  "commit": "7e9285f84cc6b52165dbc97b9a0d4f059d0f6818",
+  "commit": "8e2aaf58b416eecf27f0021e9ee770a34688fff9",
   "checkout": null,
   "context": {
     "cookiecutter": {
@@ -11,7 +11,8 @@
       "project_slug": "rra-tools",
       "package_name": "rra_tools",
       "project_short_description": "Common utilities for IHME Rapid Response team pipelines.",
-      "_template": "https://github.com/collijk/python-package-cookiecutter"
+      "_template": "https://github.com/collijk/python-package-cookiecutter",
+      "_commit": "8e2aaf58b416eecf27f0021e9ee770a34688fff9"
     }
   },
   "directory": null

.github/alternative_workflows/build_docs.yml

@@ -0,0 +1,21 @@
+name: Build and Deploy Docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+    types:
+      - closed
+
+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

.pre-commit-config.yaml.rej

@@ -0,0 +1,13 @@
+diff a/.pre-commit-config.yaml b/.pre-commit-config.yaml	(rejected hunks)
+@@ -25,11 +25,6 @@ repos:
+         # Add --fix, in case you want it to autofix when this hook runs
+         entry: poetry run ruff check --force-exclude --fix
+         require_serial: true
+-      - id: ruff
+-        name: ruff
+-        # Add --fix, in case you want it to autofix when this hook runs
+-        entry: poetry run ruff check --force-exclude
+-        require_serial: true
+         language: system
+         types: [ python ]
+       - id: mypy

docs/api_docs.md

@@ -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/rra_tools
@@ -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:

mkdocs.yml

@@ -0,0 +1,8 @@
+diff a/mkdocs.yml b/mkdocs.yml	(rejected hunks)
+@@ -73,5 +79,5 @@ extra_javascript:
+   - https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js
+   - _javascript/tablesort.js
+   - _javascript/mathjax.js
+-  - https://polyfill.io/v3/polyfill.min.js?features=es6
++  - https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6
+   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js

mkdocs.yml.rej

@@ -43,6 +43,9 @@ requests = "^2.32.2"
 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 = "*"
@@ -90,6 +93,9 @@ ignore-init-module-imports = true
     "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

poetry.lock

@@ -0,0 +1,10 @@
+diff a/pyproject.toml b/pyproject.toml	(rejected hunks)
+@@ -90,7 +96,7 @@ classmethod-decorators = [
+ ]
+ 
+ [tool.ruff.lint.flake8-tidy-imports]
+-ban-relative-imports = true
++ban-relative-imports = "all"
+ 
+ [tool.pytest.ini_options]
+ addopts = """\

pyproject.toml

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