Alberto-Codes/docvet
GitHub: Alberto-Codes/docvet
一款Python文档字符串质量检查工具，超越格式和存在性检查，验证完整性、准确性、新鲜度及mkdocs渲染兼容性。
Stars: 0 | Forks: 0
[](https://pypi.org/project/docvet/)
[](https://github.com/Alberto-Codes/docvet/actions)
[](https://codecov.io/gh/Alberto-Codes/docvet)
[](https://github.com/Alberto-Codes/docvet/blob/main/LICENSE)
[](https://pypi.org/project/docvet/)
[](https://github.com/Alberto-Codes/docvet)
# docvet
**更好的文档字符串，更好的 AI。**
## 为什么选择 docvet？
ruff 检查文档字符串的格式。interrogate 检查它们是否存在（但已停止维护）。docvet 检查它们是否正确 —— 并且现在也覆盖了存在性检查。现有工具涵盖风格；docvet 则提供它们缺失的层面：
| 层面 | 检查 | ruff | interrogate | pydoclint | **docvet** |
|-------|-------|------|-------------|-----------|------------|
| 1. 存在性 | "是否存在文档字符串？" | -- | 是 (已停止维护) | -- | **是** |
| 2. 风格 | "格式是否正确？" | 是 | -- | -- | -- |
| 3. 完整性 | "是否包含所有必需部分？" | -- | -- | 部分 | **是** |
| 4. 准确性 | "是否与当前代码匹配？" | -- | -- | -- | **是** |
| 5. 渲染 | "mkdocs 能否正确渲染它？" | -- | -- | -- | **是** |
| 6. 可见性 | "mkdocs 是否能看到该文件？" | -- | -- | -- | **是** |
**pydoclint** 涵盖 3 个结构类别（Args, Returns, Raises）。docvet 仅在增强功能方面就有 10 条规则，包括 Raises、Yields、Receives、Warns、Attributes、Examples 和交叉引用。加上存在性（覆盖率指标 + 阈值强制执行）、新鲜度（通过 git diff/blame 检测过时）、griffe 渲染兼容性和 mkdocs 覆盖率：共 5 项检查 20 条规则，涉足其他工具未曾触及的领域。
**[快速入门](#quickstart)** | **[GitHub Action](#github-action)** | **[Pre-commit](#pre-commit)** | **[配置](#configuration)** | **[AI Agent 集成](#ai-agent-integration)** | **[文档](https://alberto-codes.github.io/docvet/)**
## 检查内容
**存在性** (existence) -- 1 条规则：
`missing-docstring`
**增强功能** (completeness) -- 10 条规则：
`missing-raises` `missing-yields` `missing-receives` `missing-warns` `missing-other-parameters` `missing-attributes` `missing-typed-attributes` `missing-examples` `missing-cross-references` `prefer-fenced-code-blocks`
**新鲜度** (accuracy) -- 5 条规则：
`stale-signature` `stale-body` `stale-import` `stale-drift` `stale-age`
**Griffe** (rendering) -- 3 条规则：
`griffe-unknown-param` `griffe-missing-type` `griffe-format-warning`
**覆盖率** (visibility) -- 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` 中的检查会导致非零退出代码；未列出的检查被视为警告。
```
[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: v1.2.0
hooks:
- id: docvet
```
对于 griffe 渲染检查，添加可选依赖项：
```
repos:
- repo: https://github.com/Alberto-Codes/docvet
rev: v1.2.0
hooks:
- id: docvet
additional_dependencies: [griffe]
```
## GitHub Action
将 docvet 添加到您的 GitHub Actions 工作流：
```
- uses: Alberto-Codes/docvet@v1
```
带版本固定和自定义参数：
```
- uses: Alberto-Codes/docvet@v1
with:
version: '1.2.0'
args: 'check --all'
```
对于 griffe 渲染检查，在运行 docvet 之前安装 griffe：
```
- uses: actions/setup-python@v5
with:
python-version: '3.12'
- run: pip install griffe
- uses: Alberto-Codes/docvet@v1
with:
args: 'check --all'
```
## AI Agent 集成
有关特定工具的集成代码片段，请参阅 [完整的 AI Agent 集成指南](https://alberto-codes.github.io/docvet/ai-integration/)。
将 docvet 添加到您的 AI 编码工作流中。将此内容放入您的 `CLAUDE.md`、`.cursorrules` 或 agent 配置中：
```
## Docstring 质量
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 coverage` | 查找对 mkdocs 不可见的文件 |
| `docvet griffe` | 检查 mkdocs 渲染兼容性 |
## 更好的文档字符串，更好的 AI
AI 编码 agent 在生成和修改代码时，依赖文档字符串作为上下文。Agent 修改代码但经常让文档字符串变得过时，研究表明过时或不正确的文档不仅无益，反而 actively harmful（主动有害），比没有文档更糟糕：
- 不正确的文档 [将 LLM 任务成功率降低了 22.6 个百分点](https://arxiv.org/abs/2404.03114)
- 注释密度 [将代码生成质量提高了 40-54%](https://arxiv.org/abs/2402.13013)
- 误导性注释 [将 LLM 故障定位准确率降低至 24.55%](https://arxiv.org/abs/2504.04372)
- 如果没有文档字符串，[性能会大幅下降](https://arxiv.org/abs/2508.09537)
正如 [2025 年 DORA 报告](https://cloud.google.com/resources/content/2025-dora-ai-assisted-software-development-report) 所言：“AI 并不修复团队；它放大了团队已有的特质。”[唯一与 AI 生产力相关的指标是代码质量](https://stackoverflow.blog/2026/02/04/code-smells-for-ai-agents-q-and-a-with-eno-reyes-of-factory)。
docvet 的新鲜度检查捕捉过时文档造成的准确性差距，其增强规则确保 agent 用作上下文的文档字符串部分是完整的。在您的 CI、pre-commit 钩子或 agent 工具链中运行 `docvet check`。
## 徽章
向您的项目添加徽章以展示您的文档已经过审查：
```
[](https://github.com/Alberto-Codes/docvet)
```
## 使用情况
您正在使用 docvet 吗？提交 Pull Request 将您的项目添加到这里。
## 许可证
MIT —— 详情请参阅 [LICENSE](https://github.com/Alberto-Codes/docvet/blob/main/LICENSE)。
标签：AI训练数据, DNS解析, Docstring, Interrogate, Linter, MkDocs, pptx, PyPI, Python, Python包, Ruff, SAST, SOC Prime, 代码规范, 单元测试, 开发工具, 开源项目, 技术债务, 文档字符串, 无后门, 盲注攻击, 网络安全研究, 逆向工具, 错误基检测, 静态代码分析