pydocformatter¶
pydocformatter is a Ruff-style Python linter and formatter for docstrings and comments.
Install it as a standalone tool:
uv tool install pydocformatter
Check a project:
pydocfmt check
Apply fixes:
pydocfmt check --fix
Start here¶
- Tutorial for a first end-to-end run.
- Comparison for a factual guide to related Python documentation and formatting tools.
- Demonstration for a tested end-to-end transformation, diagnostics, and complete diff.
- Articles explaining safe docstring formatting and tool ownership in a Ruff project.
- Installation for pip, uv, pipx, and pre-commit setup.
- Checking for diagnostics, exit codes, diffs, suppressions, and file previews.
- Formatting for automatic fixes and formatting scope.
- Configuration for
pyproject.toml, discovery, and overrides. - Rules for generated rule documentation.
- Settings for generated configuration reference.
What it covers¶
pydocformatter formats Python docstrings and comments while leaving ordinary Python expression formatting to tools such as Ruff. It understands docstring conventions, file selection, rule selection, suppressions, line endings, indentation, protected code examples, and structured comment regions.
Rule families¶
- PCF comment formatting rules cover standalone comments, trailing comments, directives, suppressions, and comment source text.
- PDF docstring formatting rules cover docstring literals, source layout, semantic sections, documentation consistency, missing documentation, and typed entries.