| name | document-python-code |
| description | Document new Python code and review documentation affected by code changes according to PEP 257 and repository conventions. Use when implementing or modifying Python modules, public APIs, classes, functions, methods, configuration, behavior, errors, side effects, examples, or user-facing workflows; also use for documentation audits and docstring reviews. |
Document Python Code
Establish the documentation contract
- Read repository instructions, formatter and linter configuration, nearby docstrings, package READMEs, and tests before editing documentation.
- Inspect the complete code diff, including callers and tests. Identify new or changed public behavior, parameters, return values, exceptions, side effects, state transitions, configuration, and restrictions.
- Treat documentation as part of the implementation. Update it in the same change as the code and keep it limited to behavior the code and tests support.
Apply PEP 257
- Add docstrings to modules and exported functions, classes, methods, and public constructors. Document private objects only when their contract or reasoning is not evident.
- Use
"""triple double quotes""". Use raw triple-double-quoted strings when backslashes must remain literal.
- Write a one-line docstring as a concise imperative phrase ending in a period, such as
"""Return the cached repository metadata.""" Do not repeat the callable signature.
- Start a multi-line docstring with a one-line summary, add a blank line, then explain the contract. Put its closing quotes on a separate line.
- Describe applicable arguments, return values, yielded values, exceptions, side effects, preconditions, and keyword-argument guarantees. Do not restate type annotations without adding meaning.
- Summarize a class's behavior and public interface. Document constructor behavior in
__init__. State whether subclass behavior extends or overrides its parent when relevant.
- Keep indentation consistent and omit leading or trailing blank lines inside the docstring.
Follow the repository's configured docstring markup style, such as Google, NumPy, or Sphinx. PEP 257 defines structure, not a markup syntax.
Review affected documentation
Search beyond the edited symbol. Review module and package docstrings, __init__.py exports, READMEs, tutorials, examples, configuration references, CLI help, comments, and tests that describe the changed behavior.
- Remove stale claims and obsolete examples.
- Update renamed symbols, parameters, defaults, exceptions, commands, and environment variables.
- Preserve useful rationale in comments; remove comments that merely narrate the code.
- Keep terminology and examples consistent across all affected documentation.
- Avoid speculative promises, implementation trivia, and documentation for behavior that does not exist.
Verify the result
- Re-read each docstring beside its implementation and tests.
- Run the repository's formatter, documentation linter, type checker, and relevant tests.
- Search for old names and changed values to catch stale references.
- Report which documentation changed, which checks ran, and any documentation that still requires external confirmation.
