Skip to content

Curated API Reference Docs

The Zensical docs now use mkdocstrings-python for a curated API reference.

Dependency and configuration:

  • mkdocstrings-python is a dev dependency in pyproject.toml.
  • zensical.toml configures [project.plugins.mkdocstrings.handlers.python].
  • The Python handler uses paths = ["."] because the importable package root is the repository root and documented identifiers are under src.*.
  • Source blocks are hidden globally with show_source = false to keep the reference concise.

Scope:

  • Document stable user-facing entrypoints: monitor types, experiment specs and runners, environment factories/constraint wrappers, verification helpers, and plotting helpers.
  • Do not generate pages for every helper in src/.
  • Keep private names starting with _ out of the API pages unless a later feature intentionally promotes them.

When adding a new stable user-facing API, add it to the relevant page under docs/api/ and run:

  • uv run zensical build --strict

If a generated block is too sparse, prefer a small behavior-focused docstring on the public object over long prose in the API page.