python-docs

Python documentation conventions

Docstrings are the API's reference manual: editors, help(), and doc generators render them, and LLM coding agents read them to learn an API. These rules say where they go, what style they take, and how the linter enforces them. For the code itself see the python-style skill.

1. A docstring on every public API, Google style

Every public module, class, function, and method carries a docstring; private (_-prefixed) and trivial dunder methods do not need one. Use Google style — a one-line imperative summary, then Args:, Returns:, Raises: as needed:

def parse(line: str) -> tuple[str, str]:
    """Split a KEY=VALUE line into its key and value.

    Args:
        line: A single ``key=value`` pair; whitespace around each side is trimmed.

    Returns:
        The ``(key, value)`` pair.

    Raises:
        ValueError: If the separator is missing or the key is empty.
    """

Document behavior and invariants the caller can rely on, not the implementation. Types live in the annotations (see python-typing), so do not repeat them in the docstring prose.

2. Module and package docstrings

Every module starts with a docstring on line 1 (after from __future__ import annotations if present) describing what it provides. A package's docstring lives in its __init__.py.

3. Enforce with ruff's D rules

Make docstring presence and format a lint error, not a review nit — add the D family and pin the convention so ruff checks Google style specifically:

[tool.ruff.lint]
extend-select = ["D"]

[tool.ruff.lint.pydocstyle]
convention = "google"

[tool.ruff.lint.per-file-ignores]
"tests/**" = ["D"]   # tests document themselves through their names

uv run ruff check now flags missing and malformed docstrings.

4. Generate an LLM-ready CLI reference

A Click command tree (Typer compiles to Click) already knows every command, flag, and help string — publish it as one markdown page per command that humans, search engines, and LLMs can read: