python-api-docs

Python API Documentation

pythonica:python-code-style teaches you to write google-style docstrings; this skill renders them into a published API reference. The toolchain is Sphinx + autodoc + napoleon + MyST, gated strictly in CI so the reference can't silently rot. For the general documentation rules (tone, brevity, structure) this toolchain serves, see praxis:docs-patterns.

Core Concepts

1. Docstrings are the single source

Autodoc imports your package and extracts docstrings at build time. The reference is generated, never hand-copied -- so it can't drift from the code.

2. Annotations render themselves -- don't duplicate types

With type hints present, autodoc renders them into the signature (autodoc_typehints defaults to "signature"). Restating (str) in an Args line duplicates the annotation and drifts when the type changes. Keep Args descriptions prose-only.

3. Examples that run can't rot

The >>> Example blocks python-code-style recommends are executable. Run them under sphinx.ext.doctest and a broken example fails the build instead of misleading a reader.

4. A strict build is a CI gate

sphinx-build -W turns every warning (a missing module, an unresolved :func:, a bad cross-reference) into an error. Wire it into CI and the docs stay correct on every PR.

Quick Start

Declare the toolchain as an optional-dependency extra, then build:

# pyproject.toml
[project.optional-dependencies]
docs = [
    "sphinx>=9,<10",     # site generator (reads google docstrings via napoleon)
    "myst-parser>=5,<6", # author pages in Markdown, not reStructuredText
    "furo>=2025.12",     # theme (CalVer -- date floor, no semver major to cap)
]

pip install -e '.[docs]'
sphinx-build -W -b html    docs docs/_build/html      # strict HTML build
sphinx-build -W -b doctest docs docs/_build/doctest    # run every >>> example

Fundamental Patterns

Pattern 1: Wire Sphinx + MyST + napoleon (conf.py)