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:

• Give every command and option a clear help string; expose the root command from your CLI module.

• Copy templates/docgen.py to src/myapp/tools/docgen.py and point its import at your command (for Typer, convert with typer.main.get_command(app)). It walks the tree writing timestamp-free markdown, so the output is reproducible.

• It imports your application packages, so it runs in-project with uv run — it is not a separate tool. Add a Makefile target:

  docs: ## Regenerate the CLI reference (docs/cli) from the command tree
      uv run python -m myapp.tools.docgen --out docs/cli
  

• Commit the generated docs/cli and refresh it whenever commands or flags change, so the reference never drifts from the tool.

For style see the python-style skill; for the Makefile and layout see python-project.