Rewrite Python Docs

Rewrite Python Docs

Use source code as the source of truth. Treat existing docs, docstrings, tests, and examples only as weak hints.

Guidelines

• Inspect pyproject.toml, zensical.toml, noxfile.py, .config/mise/, public exports, source code, and tests before editing.
• Run scripts/gen-ref-pages.py to regenerate reference pages under docs/reference/. The script will output a navigation table that can be copy-pasted into zensical.toml.
• Files to update:
  • docstrings in source code
  • docs/ (excluding generated docs/reference/)
  • description in pyproject.toml and zensical.toml
  • inventories in zensical.toml if needed
• DO NOT EDIT:
  • generated reference pages under docs/reference/
• Existing docs, docstrings, tests, examples may be rough, missing, incomplete or misleading, it only serves as weak hint.
• Favor bold, comprehensive rewrites over minor or incremental edits.
• Keep docs concise, fluent, example-first.
• Source code is the source of truth.
• Use Google style docstrings. Read google-style.md for details.
• Prefer Examples: sections with compact doctests for public APIs when the example is deterministic, useful, and runnable.
• Treat doctests as executable tests, not decorative snippets; keep fixture-heavy, parametrized, or unstable behavior in tests/.
• Use markdown in docstrings:
  • Use single backticks for inline code, NOT double backticks.
  • Cross-references are written as Markdown reference-style links: [Object 1][full.path.object1].

Suggested Layout

docs/
  README.md
  getting-started/
    ...
  guides/
    ...
  concepts/
    ...
  reference/  # generated, DO NOT EDIT
    package/
      README.md
      submodule.md
  advanced/
    ...

• Keep only the sections the project needs.
• Keep navigation shallow.

mkdocstrings Notes

• The project uses zensical with mkdocstrings.
• The __init__ method is merged into the class' signature and docstring.
• The first line in __init__ methods' docstrings is ignored.

Validation

• Run rumdl fmt .. Treat its findings as weak hints, not strong constraints.
• Run uv run pytest ... for changed doctests.
• Run mise run lint.
• Run mise run docs:build.
• If validation fails for unrelated reasons, separate those failures from the docs change and report them clearly.