feat(template): generate API reference pages from modules

Add a mise task that builds API reference pages from public Python modules and updates the docs template to rely on generated pages instead of a manual reference stub.

This helps generated projects keep their API docs and navigation in sync with the codebase while reducing template maintenance.

Author: liblaf

.config/cspell.config.yaml

@@ -14,18 +14,22 @@ maxFileSize: 500KB
 useGitignore: true
 words:
   - arithmatex
+  - bfadeab
   - chtml
+  - codspeedhq
   - direnv
   - envops
   - envrc
   - fieldz
+  - fspath
   - grimp
   - hynek
   - inlinehilite
   - kwargs
   - liblaf
   - linenums
   - lucide
+  - mergery
   - mkdocs
   - mkdocstrings
   - noxfile
@@ -44,6 +48,7 @@ words:
   - pyrightconfig
   - pytest
   - pyvista
+  - rumdl
   - sdist
   - strftime
   - taiki

mise-tasks/gen/ref-pages.py

@@ -0,0 +1,104 @@
+#!/usr/bin/env -S uv run --script
+# /// script
+# requires-python = ">=3.14"
+# dependencies = [
+#     "tomlkit>=0.14.0",
+# ]
+# ///
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import os
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+import tomlkit
+
+MARKDOWN_TEMPLATE: str = """\
+::: {module_path}
+    options:
+        toc_label: {module_path}
+"""
+MODULE_SYMBOL: str = '<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>'
+
+
+class Args(argparse.Namespace):
+    api_root: Path
+    docs_dir: Path
+    print_nav: bool
+    src: Path
+
+
+@dataclasses.dataclass
+class Nav:
+    module_path: str = ""
+    index: str | None = None
+    children: dict[str, Nav] = dataclasses.field(default_factory=dict)
+
+    def add(self, parts: Sequence[str], full_doc_path: Path) -> None:
+        if not parts:
+            self.index = os.fspath(full_doc_path)
+            return
+        if parts[0] in self.children:
+            child = self.children[parts[0]]
+        else:
+            child = type(self)(
+                module_path=f"{self.module_path}.{parts[0]}"
+                if self.module_path
+                else parts[0]
+            )
+            self.children[parts[0]] = child
+        child.add(parts[1:], full_doc_path)
+
+    def dump(self) -> Any:
+        children: list[Any] = []
+        if self.index is not None:
+            children.append(self.index)
+        for _, child in sorted(self.children.items()):
+            children.append(child.dump())
+        if len(children) == 1:
+            return children[0]
+        return {f"{MODULE_SYMBOL} {self.module_path}": children}
+
+
+def is_public(part: str) -> bool:
+    return not part.startswith("_") or (part.startswith("__") and part.endswith("__"))
+
+
+def parse_args() -> Args:
+    parser: argparse.ArgumentParser = argparse.ArgumentParser()
+    parser.add_argument("src", nargs="?", default="src", type=Path)
+    parser.add_argument("--api-root", default="reference/", type=Path)
+    parser.add_argument("--docs-dir", default="docs/", type=Path)
+    parser.add_argument("--print-nav", action="store_true")
+    return parser.parse_args(namespace=Args())
+
+
+def main() -> None:
+    args: Args = parse_args()
+    nav = Nav()
+    for path in args.src.rglob("*.py"):
+        relative: Path = path.relative_to(args.src)
+        module_path: Path = relative.with_suffix("")
+        parts: tuple[str, ...] = tuple(module_path.parts)
+        if not all(is_public(part) for part in parts):
+            continue
+        doc_path: Path = relative.with_suffix(".md")
+        if parts[-1] == "__init__":
+            parts: tuple[str, ...] = parts[:-1]
+            doc_path: Path = doc_path.with_name("README.md")
+        elif parts[-1] == "__main__":
+            continue
+        doc_path: Path = args.api_root / doc_path
+        full_doc_path: Path = args.docs_dir / doc_path
+        full_doc_path.parent.mkdir(parents=True, exist_ok=True)
+        full_doc_path.write_text(MARKDOWN_TEMPLATE.format(module_path=".".join(parts)))
+        nav.add(parts, doc_path)
+    print(tomlkit.dumps(nav.dump()))
+
+
+if __name__ == "__main__":
+    main()

template/.config/mise/conf.d/50-python.toml

@@ -19,11 +19,15 @@ description = "Serve the documentation site locally"
 run = ["rm --force --recursive '{{ config_root }}/.cache'", "zensical serve"]
 
 [tasks."gen:init"]
-description = "Generate __init__.py files from __init__.pyi stubs"
+description = "Generate lazy-loading __init__.py files from __init__.pyi stubs"
 file = "https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/mise-tasks/gen/init.py"
 
+[tasks."gen:ref-pages"]
+description = "Generate API reference pages from public Python modules"
+file = "https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/mise-tasks/gen/ref-pages.py"
+
 [tasks.install]
-description = "Install project dependencies from lockfiles"
+description = "Install project dependencies from pixi.lock or uv.lock"
 file = "https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/mise-tasks/install.sh"
 
 [tasks.lint]
@@ -35,9 +39,9 @@ description = "Lint and format Python files"
 run = ["lint-imports", "ruff check --fix", "ruff format"]
 
 [tasks."lint:toml"]
-description = "Sort, format, and lint TOML files"
+description = "Sort, format, and lint TOML files with toml-sort and tombi"
 file = "https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/mise-tasks/lint/toml.sh"
 
 [tasks.upgrade]
-description = "Upgrade project dependencies from lockfiles"
+description = "Upgrade project dependencies from pixi.lock or uv.lock"
 file = "https://raw.githubusercontent.com/liblaf/copier-python/refs/heads/main/mise-tasks/upgrade.sh"

template/README.md.jinja

@@ -1,7 +1,6 @@
 <!-- -*- mode: markdown; -*- -->
 
 <div align="center" markdown>
-<a name="readme-top"></a>
 
 ![{{github_repo}}](https://socialify.git.ci/{{github_user}}/{{github_repo}}/image?description=1&forks=1&issues=1&language=1&name=1&owner=1&pattern=Transparent&pulls=1&stargazers=1&theme=Auto)
 
@@ -12,7 +11,7 @@
 
 [Changelog](https://github.com/{{github_user}}/{{github_repo}}/blob/main/CHANGELOG.md) · [Report Bug](https://github.com/{{github_user}}/{{github_repo}}/issues) · [Request Feature](https://github.com/{{github_user}}/{{github_repo}}/issues)
 
-![](https://cdn.jsdelivr.net/gh/andreasbm/readme/assets/lines/rainbow.png)
+![Rule](https://cdn.jsdelivr.net/gh/andreasbm/readme/assets/lines/rainbow.png)
 
 </div>
 
@@ -32,7 +31,7 @@ uv add {{ package_name }}
 
 You can use Github Codespaces for online development:
 
-[![](https://github.com/codespaces/badge.svg)](https://codespaces.new/{{github_user}}/{{github_repo}})
+[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/{{github_user}}/{{github_repo}})
 
 Or clone it for local development:
 

template/docs/README.md

@@ -1 +1 @@
---8<-- "README.md"
+TODO

template/docs/reference/README.md.jinja

@@ -10,7 +10,6 @@ site_author = "{{ author_name }}"
 # Navigation
 nav = [
   { "Home" = "README.md" },
-  { "API Reference" = "reference/README.md" },
 ]
 # Repository
 repo_url = "https://github.com/{{ github_user }}/{{ github_repo }}"
@@ -98,11 +97,10 @@ extensions = [
 find_stubs_package = true
 show_inheritance_diagram = true
 # Headings
-parameter_headings = true
+heading_level = 1
 show_root_heading = true
 show_symbol_type_heading = true
 show_symbol_type_toc = true
-type_parameter_headings = true
 # Members
 inherited_members = true
 filters = "public"