docs: auto-generated API reference site

[adilfaisal01]

What

An mkdocs-material API reference site whose pages are generated from source, not hand-maintained, plus a GitHub Pages deploy workflow.

The zero-maintenance mechanism

scripts/gen_api.py walks each subpackage's __all__ and emits one page per subpackage plus the nav:

7 exports -> 8 exports, 0 config edits

Verified by temporarily injecting a class into controllers/, confirming it rendered end-to-end in the built HTML, then reverting. Subpackages without __all__ (components.py, utils/) fall back to an AST scan of their source files. Adding an export is all it takes for it to show up in the docs.

The non-obvious part

The source mixes Google param sections (Args: / Returns:) with Sphinx roles (:class:, :meth:, :func:) and math (:math:, .. math::). griffe's Google parser doesn't understand the Sphinx half, so out of the box:

• 86 Sphinx markers leak as literal text
• every formula renders as raw markup (:math: u = -K(x - x_t))

scripts/sphinx_compat.py is a griffe extension normalizing all three forms -> 0 leaks, 28 rendered MathJax blocks.

Removing it does not fail the build — you silently get broken math. Also: the extensions: key must sit under options: in mkdocs.yml, not at handler level, or it is ignored.

Verification

Check	Result
Build	exit 0, 6.9s, 18 pages
Leaked markers (rendered prose)	0
MathJax blocks	28
Auto-update	7 -> 8 exports, 0 config edits

Deliberate choices worth reviewing

• --strict is omitted. griffe reports unannotated public params as warnings (204 today), so --strict is red out of the box. Add it once annotations improve.
• Generated output is gitignored (docs/reference/, docs/SUMMARY.md, site/) — CI regenerates on every run, so nothing stale can be committed.
• GitHub Pages is now enabled on the repo with build_type: workflow; this workflow deploys to https://shinro-xyz.github.io/shinro-python-modules/ on merge to main.

Honest limitation

53% of public symbols have docstrings (~281 render as bare signatures; codegen/ is weakest, and only 121 functions are fully annotated). No generator fixes this — it's a source-coverage limit, not a tooling one. Widening pyright's coverage past its current 5 subpaths would improve the docs for free.

Sphinx alternative, if preferred

A Sphinx + napoleon + Furo POC was also built: 0 normalization glue needed, since the docstrings already are Sphinx-flavored. Trade-off is RST config surface, ~40s builds, and a less polished theme.

Commands

make docs         # install docs toolchain
make docs-serve   # regenerate + serve at :8000
make docs-build   # regenerate + build site/

Generated with Hermes Agent