Skip to content

Better docstrings, better AI.

PyPI version Python versions CI Coverage License docs vetted

docvet vets your Python docstrings for completeness, accuracy, and rendering compatibility — the layers beyond style and presence that tools like ruff and interrogate don't cover.

Quick Start

pip install docvet && docvet check --all

The Quality Model

Most tools stop at style and presence. docvet picks up where they leave off:

Layer Check What It Catches Tool
1 Style Formatting, conventions ruff D rules
2 Presence Missing docstrings interrogate
3 Completeness Missing sections (Raises, Yields, Attributes) docvet enrichment
4 Accuracy Stale docstrings after code changes docvet freshness
5 Rendering Broken mkdocs output docvet griffe
6 Visibility Packages hidden from doc generators docvet coverage

Checks

  • Enrichment

    Detects missing Raises, Yields, Attributes, and Examples sections via AST analysis. 10 rules.

    Learn more

  • Freshness

    Flags code changes without docstring updates using git diff and git blame. 5 rules, two modes.

    Learn more

  • Coverage

    Finds missing __init__.py files that hide packages from documentation generators.

    Learn more

  • Griffe

    Captures griffe parser warnings that break mkdocs rendering. 3 rules.

    Learn more

Installation

pip install docvet

Includes enrichment, freshness, and coverage checks.

pip install docvet[griffe]

Adds the optional griffe rendering compatibility check for mkdocs projects.

Usage

Run docvet against your entire codebase:

docvet check --all

Or check only files with unstaged changes (the default):

docvet check

Or check only staged files, ideal for pre-commit hooks:

docvet check --staged

Here's what the output looks like when findings exist:

src/myapp/utils.py:42: missing-raises Function 'parse_config' raises ValueError but Raises section is missing [required]
src/myapp/utils.py:87: stale-signature Function 'validate_input' signature changed without docstring update [required]
src/myapp/models.py:15: missing-attributes Class 'User' has 3 undocumented attributes [required]
Vetted 12 files [enrichment, freshness, coverage] — 3 findings (3 required, 0 recommended). (0.2s)

Each finding shows the file, line number, rule name, a human-readable message, and severity. The summary line confirms what was checked and how long it took. When all docstrings are clean, you see:

Vetted 12 files [enrichment, freshness, coverage] — no findings. (0.1s)

What's Next