Writing Docstrings

Default to NumPy style. It handles complex parameter descriptions better than the alternatives: each parameter gets its own block with room for a type, a default, constraints, and prose, instead of being squeezed onto one indented line.

Source: numpydoc style guide.

When to Use

Load this before writing or editing:

• Any public module, class, or function — no leading underscore
• A public method on a public class
• A function whose parameters carry units, ranges, defaults, or invariants
• Any change to an existing docstring's structure

When NOT to apply: private helpers, dunders, nested closures, @overload declarations, .../pass stubs, @property setters and deleters, and test functions in test_*.py are all exempt. The checker skips them too. A private helper with a genuinely subtle contract still deserves a docstring — the exemption means "not required", not "not allowed".

Section Order

NumPy fixes the order. Use only the sections you need, but keep them in this sequence:

1. Short summary
2. Deprecation warning
3. Extended Summary
4. Parameters
5. Returns
6. Yields
7. Receives
8. Other Parameters
9. Raises
10. Warns
11. Warnings
12. See Also
13. Notes
14. References
15. Examples

Classes omit Returns and add Attributes (directly below Parameters) and an optional Methods. Modules use summary, extended summary, routine listings, See Also, Notes, References, Examples.

Warns and Warnings are different sections. Warns documents warnings the code raises; Warnings is free-text caution for the reader.

Core Pattern

Every section heading is underlined with hyphens. Parameters are name : type with the description indented beneath.

def fetch_batch(client, batch_size, timeout_s=30.0, *, retries=3):
    """Fetch one batch of records from the upstream service.

    Blocks until the batch arrives or the retry budget is exhausted. Partial
    batches are returned as-is; the caller decides whether a short batch ends
    the stream.

    Parameters
    ----------
    client : HttpClient
        Configured client. Must already be authenticated.
    batch_size : int
        Number of records to request. Must be in ``1..1000``; the service
        rejects larger values.
    timeout_s : float, default 30.0
        Per-attempt socket timeout in seconds. Does not bound total wall time,
        which is roughly ``timeout_s * retries``.
    retries : int, default 3
        Attempts before giving up, counting the first attempt.

    Returns
    -------
    list of Record
        Between zero and `batch_size` records, in service order.

    Raises
    ------
    ValueError
        If `batch_size` falls outside the accepted range.
    TimeoutError
        If every attempt exceeds `timeout_s`.
    """

Note what the parameter blocks carry that a one-liner cannot: the accepted range for batch_size, the fact that timeout_s is per attempt rather than total, and the off-by-one clarification that retries counts the first attempt. That is the reason for the default.

Parameter Syntax

The summary line is one line, ends with a period, and does not repeat the function's own name.

The Alternates

Google and reST are acceptable, under one condition: match the file you are editing. A file already written in Google style stays in Google style — a mixed-convention file is worse than either convention.

# Google — compact, but the type and prose share one line
"""
Args:
    batch_size (int): Number of records; must be in 1..1000.
"""

# reST — Sphinx-native field lists
"""
:param int batch_size: Number of records; must be in 1..1000.
"""

Switching a whole project is a deliberate decision, not a side effect of one edit. Record it in the project's pyproject.toml, so every session, teammate, and CI run agrees without anyone remembering a flag:

[tool.reliable-python]
docstring-style = "google"   # numpy (default), google, rest, or any

Precedence is --docstring-style → RELIABLE_PYTHON_DOCSTYLE → pyproject.toml → numpy. Check what is actually in effect with:

python3 <skill-directory>/../review-code-quality/scripts/audit_python.py --print-docstring-style

The resolved convention is also stated at the end of the injected session policy, so it is visible without running anything.

Checker Rules

DOC02 never fires on a summary-only docstring. One line with no sections is valid NumPy, valid Google, and valid reST, so there is nothing to disagree with. The rule fires only on positive evidence of a competing convention.

Use this project's suppression form, not numpydoc's # numpydoc ignore=:

# quality: ignore[DOC01] - re-exported for backward compatibility only
def legacy_entry_point(payload):
    return parse(payload)

Common Mistakes

Missing the space before the colon. x: int is not NumPy — the spec requires x : int. Without the space, tooling reads the whole line as a name.

Underline shorter than the heading. Parameters needs its hyphens; a truncated underline silently drops the section from rendered docs.

Documenting some parameters. A Parameters section listing three of five reads as complete and is worse than no section at all. That is DOC03.

Restating the signature. alpha : int — the alpha value costs a line and adds nothing. Document the constraint, the unit, or the invariant, or leave the parameter out of the docstring and let the type annotation speak.

Writing Returns for a generator. Generators use Yields. If it also consumes .send() values, add Receives below Yields.

Rationalizations