docvet

docvet

更好的文档字符串，更好的 AI。

为什么选择 docvet？

docvet 将文档字符串存在性指标、结构检查、基于历史记录的过时信号和渲染器诊断整合到一个 CLI 中，并提供编辑器和 Agent 接口。这些检查有助于审阅者发现文档缺漏；但无法证明文档内容正确描述了运行时行为。

层级	检查项	ruff	interrogate	pydoclint	docvet
1. 存在性	“是否存在文档字符串？”	是（D 规则，需选择启用）	是，带覆盖率指标	跳过缺失的文档字符串	是，带覆盖率指标
2. 风格	“格式是否一致？”	是（D 规则，需选择启用）	--	部分解析／风格检查	有限的格式检查
3. 完整性	“各个章节是否与代码结构一致？”	部分支持（D 规则；预览中的 DOC 规则）	--	参数、返回值、生成值、引发的异常、属性、类型提示	基于 AST 的章节与一致性检查
4. 准确性	“哪些内容因过时而需要审阅？”	上述结构检查	--	上述结构检查	Git diff/blame 启发式检查；不提供语义证明
5. 渲染	“是否存在解析器警告？”	--	--	--	Griffe 诊断
6. 可见性	“软件包发现是否不完整？”	--	--	--	缺失 __init__.py 检查

对比信息于 2026-10-21 根据主要文档进行审阅：Ruff 的 D103 存在性规则 和 DOC501 异常完整性规则（需使用 --preview 并选择规则）、pydoclint 支持的检查项与风格以及 interrogate 的覆盖率文档。具体能力取决于启用的规则和配置；-- 表示这些来源未描述相应检查。

pydoclint 支持 Google、NumPy 和 Sphinx 风格，检查参数、返回值、生成值、引发的异常、类属性和类型提示。仅 docvet 的扩展功能就包含 21 条规则，包括 Raises、Yields、Receives、Warns、Attributes、Examples、交叉引用、参数一致性等。再加上存在性（覆盖率指标 + 阈值执行）、新鲜度（基于 git diff/blame 的过时信号）、griffe 渲染兼容性和 mkdocs 覆盖率：共计 5 类检查、32 条规则。规则总数统计的是目录中的条目，并不表示不同工具之间的覆盖能力等同。

结构一致性检查会比较文档中描述的元素与代码结构。新鲜度检查利用更改历史提示哪些内容需要审阅：代码变更不一定会导致文档内容失效，而代码和文档字符串同时修改后，文档内容仍可能不准确。这两类检查都无法确立语义上的正确性。

快速入门 | GitHub Action | Pre-commit | 配置 | AI Agent 集成 | 文档

检查内容

存在性（是否存在）——2 条规则： missing-docstring overload-has-docstring

完善度（完整性）——21 条规则： 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 scaffold-incomplete

新鲜度（过时信号）——5 条规则： stale-signature stale-body stale-import stale-drift stale-age

Griffe（渲染）——3 条规则： griffe-unknown-param griffe-missing-type griffe-format-warning

覆盖率（可见性）——1 条规则： missing-init

快速开始

pip install docvet && docvet check --all

如需启用可选的 Griffe 渲染检查：

pip install docvet[griffe]

示例输出：

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]

配置

在 pyproject.toml 中通过 [tool.docvet] 进行配置。所有检查都会运行并输出检查结果。列在 fail-on 中的检查会导致退出代码非零；未列出的检查则作为警告处理。

如果 fail-on 中的某项检查无法运行——最常见的情况是未安装 docvet[griffe]，导致无法运行 griffe——那么你配置的门禁就从未得到验证，因此 docvet 会在 stderr 中报告该问题并以代码 1 退出。使用 --format json 时，run 对象会将 status 报告为 "unavailable"，并包含一个 unavailable_checks 数组，这可以将其与发现问题的门禁区分开来。设置 fail-on-unavailable = false（或传入 --no-fail-on-unavailable）即可改为发出警告并以代码 0 退出。没有任何门禁关注的不可用检查会被静默跳过——不过，决定门禁的条件不止 fail-on 中是否包含该检查：min-coverage 下限也会对 presence 设立门禁，即使没有在其中列出。

[tool.docvet]
exclude = ["tests", "scripts"]
fail-on = ["griffe", "coverage"]

[tool.docvet.freshness]
drift-threshold = 30
age-threshold = 90

Pre-commit

将以下内容添加到你的 .pre-commit-config.yaml：

repos:
  - repo: https://github.com/Alberto-Codes/docvet
    rev: v3.0.0
    hooks:
      - id: docvet

如需进行 Griffe 渲染检查，请添加可选依赖：

repos:
  - repo: https://github.com/Alberto-Codes/docvet
    rev: v3.0.0
    hooks:
      - id: docvet
        additional_dependencies: [griffe]

GitHub Action

将 docvet 添加到你的 GitHub Actions 工作流中——检查结果会以行内注释的形式显示在 PR 上：

- uses: Alberto-Codes/[email protected]

选择特定检查或固定版本：

- uses: Alberto-Codes/[email protected]
  with:
    checks: 'enrichment,freshness'
    docvet-version: '3.0.0'
    python-version: '3.13'

Griffe 渲染检查无需额外设置：无论是否固定版本，该 Action 都会安装 docvet[griffe]，因此 checks 输入中提供的所有检查都可用。请注意，1.7.0 之前的 docvet 版本声明该额外依赖时没有设置上限，因此固定这些版本会安装 Griffe 当时发布的任意版本，而不一定是 docvet 发布时所针对的版本。

行为变更——这可能会让原本通过的构建变红。

早期版本安装的是普通的 docvet，因此会跳过 Griffe 检查，也不会产生任何检查结果。现在，该检查会运行。只要 fail-on 中列出的任意检查发现问题，determine_run_outcome（src/docvet/reporting.py）就会返回退出代码 1。因此，如果你的 pyproject.toml 在 [tool.docvet] fail-on 中包含 griffe，那么即使你没有做任何改动，构建也会从绿色变为失败。本仓库自己的 ci.yml 中的 docvet 作业就是这样的使用场景。

这些并不是新问题——只是终于对原本就有问题的文档字符串运行了检查。要让构建恢复通过，请修复 Griffe 检查结果，或从 fail-on 中移除 griffe。

AI Agent 集成

如需查看特定工具的集成代码片段，请参阅完整的 AI Agent 集成指南。

将 docvet 添加到你的 AI 编码工作流中。将以下内容放入 CLAUDE.md、.cursorrules 或 Agent 配置文件：

## Docstring Quality

After modifying Python functions, classes, or modules, run `docvet check` and fix all findings before committing.

推荐的 pyproject.toml 配置：

[tool.docvet]
fail-on = ["enrichment", "freshness", "coverage", "griffe"]

子命令速查

命令	描述
docvet check	运行所有已启用的检查（默认检查 git diff 中的文件）
docvet check --all	对整个代码库运行所有检查
docvet check --staged	仅对已暂存的文件运行所有检查
docvet presence	检查是否缺少文档字符串，并提供覆盖率指标
docvet enrichment	检查是否缺少文档字符串章节
docvet freshness	通过 git 标记可能过时的文档字符串
docvet freshness --mode drift	通过 git blame 审查可能过时的内容
docvet coverage	查找 mkdocs 无法发现的文件
docvet griffe	检查与 mkdocs 的渲染兼容性
docvet fix	为缺少的文档字符串章节生成模板
docvet fix --dry-run	预览模板变更，但不写入文件
docvet config	显示带有来源注释的生效配置
docvet lsp	启动 LSP 服务，为编辑器提供实时诊断
docvet mcp	启动 MCP 服务，供 AI Agent 集成

更好的文档字符串，更好的 AI

AI 编码 Agent 在生成和修改代码时会依赖文档字符串作为上下文。Agent 会修改代码，但往往会让文档字符串过时；研究表明，过时或不准确的文档会造成实际危害，甚至比没有文档更糟：

• 错误的文档会使 大模型任务成功率降低 22.6 个百分点
• 注释密度可使代码生成效果提升 40-54%
• 误导性注释会使大模型的故障定位准确率降至 24.55%
• 缺少文档字符串时，性能会大幅下降

正如 2025 年 DORA 报告所言：“AI 不会修复一个团队；它只会放大团队已有的特质。”唯一与 AI 生产力相关的信号是代码质量。

docvet 的 freshness 启发式规则会标记可能过时的内容以供审查，其 enrichment 规则则会根据代码结构检查受支持的文档字符串章节。在 CI、pre-commit 钩子或 Agent 工具链中运行 docvet check。

徽章

为项目添加徽章，表明文档已通过检查：

[![docs vetted | docvet](https://img.shields.io/badge/docs%20vetted-docvet-purple)](https://github.com/Alberto-Codes/docvet)

使用者

你是否在使用 docvet？欢迎提交拉取请求，将你的项目添加到此处。

许可证

MIT —— 详情请参阅 LICENSE。

mcp-name: io.github.Alberto-Codes/docvet