docvet
Better docstrings, better AI.
Why docvet?
ruff checks how your docstrings look. interrogate checks if they exist (but is unmaintained). docvet checks if they're right — and now covers presence too. Existing tools cover style; docvet delivers the layers they miss:
| Layer | Check | ruff | interrogate | pydoclint | docvet |
|---|
| 1. Presence | "Does a docstring exist?" | -- | Yes (unmaintained) | -- | Yes |
| 2. Style | "Is it formatted correctly?" | Yes | -- | -- | -- |
| 3. Completeness | "Does it have all required sections?" | -- | -- | Partial | Yes |
| 4. Accuracy | "Does it match the current code?" | -- | -- | -- | Yes |
| 5. Rendering | "Will mkdocs render it correctly?" | -- | -- | -- | Yes |
| 6. Visibility | "Will mkdocs even see the file?" | -- | -- | -- | Yes |
pydoclint covers 3 structural categories (Args, Returns, Raises). docvet's enrichment alone has 20 rules, including Raises, Yields, Receives, Warns, Attributes, Examples, cross-references, parameter agreement, and more. Add presence (coverage metrics + threshold enforcement), freshness (git diff/blame staleness detection), griffe rendering compatibility, and mkdocs coverage: 31 rules across 5 checks, in territory no other tool touches.
Quickstart | GitHub Action | Pre-commit | Configuration | AI Agent Integration | Docs
What It Checks
Presence (existence) -- 2 rules:
missing-docstring overload-has-docstring
Enrichment (completeness) -- 20 rules:
missing-raises missing-returns missing-yields missing-receives missing-warns missing-deprecation missing-param-in-docstring extra-param-in-docstring missing-other-parameters missing-attributes undocumented-init-params missing-typed-attributes missing-examples missing-cross-references extra-raises-in-docstring extra-yields-in-docstring extra-returns-in-docstring missing-return-type trivial-docstring prefer-fenced-code-blocks
Freshness (accuracy) -- 5 rules:
stale-signature stale-body stale-import stale-drift stale-age
Griffe (rendering) -- 3 rules:
griffe-unknown-param griffe-missing-type griffe-format-warning
Coverage (visibility) -- 1 rule:
missing-init
Quickstart
pip install docvet && docvet check --all
For optional griffe rendering checks:
pip install docvet[griffe]
Example output:
src/mypackage/helpers.py:1: missing-docstring Module has no docstring [required]
src/mypackage/utils.py:42: missing-raises Function 'parse_config' raises ValueError but has no Raises section [required]
src/mypackage/models.py:15: stale-signature Function 'process' signature changed but docstring not updated [required]
src/mypackage/api.py:1: missing-init Package directory missing __init__.py (invisible to mkdocs) [required]
Configuration
Configure via [tool.docvet] in your pyproject.toml. All checks run and print findings. Checks listed in fail-on cause a non-zero exit code; unlisted checks are treated as warnings.
[tool.docvet]
exclude = ["tests", "scripts"]
fail-on = ["griffe", "coverage"]
[tool.docvet.freshness]
drift-threshold = 30
age-threshold = 90
Pre-commit
Add to your .pre-commit-config.yaml:
repos:
- repo: https://github.com/Alberto-Codes/docvet
rev: v1.2.0
hooks:
- id: docvet
For griffe rendering checks, add the optional dependency:
repos:
- repo: https://github.com/Alberto-Codes/docvet
rev: v1.2.0
hooks:
- id: docvet
additional_dependencies: [griffe]
GitHub Action
Add docvet to your GitHub Actions workflow — findings appear as inline annotations on your PR:
- uses: Alberto-Codes/docvet@v1
Select specific checks or pin a version:
Alberto-Codes