mcpField
D
docvet

docvet

ローカル
github.com/Alberto-Codes開発ツール106 日前に更新
リポジトリ

docvet について

docvetは、Pythonのdocstringを検査するCLIで、開発者やコードレビューのワークフローを対象とします。構造上の不足、Git履歴に基づく古さの兆候、レンダリング診断、カバレッジをまとめて確認します。古さの兆候は意味上の正確さを証明するものではありません。

主な機能

  1. 01docstringの有無とカバレッジを検査
  2. 02コード構造と記述されたセクションを照合
  3. 03Git履歴から古さの可能性を検出
  4. 04Griffeのレンダリング診断を確認
  5. 05`__init__.py` がないディレクトリを検出

活用シーン

  1. 01CIでPythonドキュメントの品質を検査
  2. 02コミット前にdocstringの不足セクションを発見
  3. 03コード変更後に古くなった可能性のある説明を確認
  4. 04LSPまたはMCPでエディターやエージェントに検査を統合

MCP 対応

`docvet mcp` でMCPサーバーを起動し、AIエージェント連携にdocstring検査機能を提供できます。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定
{
  "mcpServers": {
    "alberto-codes-docvet": {
      "command": "uvx",
      "args": [
        "docvet"
      ]
    }
  }
}
起動コマンドuvx docvet

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ
pypidocvet3.0.1

ツール

ツール一覧はまだ取得されていません

ローカルサーバーのツールはマシン上で起動して初めて取得できます。メンテナーはまだツール一覧を提供していません。

詳細

CI Coverage PyPI Python License Renovate enabled Ruff docs vetted

docvet

より良い docstring が、より良い AI を実現します。

docvet を使う理由

docvet は、docstring の有無に関するメトリクス、構造チェック、履歴に基づく古さの兆候、レンダラーの診断を、エディターやエージェントとのインターフェースを備えた 1 つの CLI に統合します。これらのチェックは、レビュアーがドキュメントの不足を見つけるのに役立ちますが、文章が実行時の動作を正しく説明していることを証明するものではありません。

レイヤーチェックruffinterrogatepydoclintdocvet
1. 有無「docstring は存在しますか？」あり（D ルール、オプトイン）あり、カバレッジメトリクス付きdocstring がない場合はスキップあり、カバレッジメトリクス付き
2. スタイル「一貫した形式になっていますか？」あり（D ルール、オプトイン）--一部の解析／スタイルチェック形式チェックは限定的
3. 完全性「セクションとコード構造は一致していますか？」一部対応（D ルール、プレビューでは DOC ルール）--引数、戻り値、yield、例外、属性、型ヒントAST ベースのセクションおよび整合性チェック
4. 正確性「古さの観点から何をレビューする必要がありますか？」上記の構造チェック--上記の構造チェックGit diff/blame のヒューリスティック。意味上の正しさは証明しません
5. レンダリング「パーサーの警告はありますか？」------Griffe の診断
6. 可視性「パッケージの検出が不完全ですか？」------__init__.py の不足チェック

比較は、主要ドキュメントに基づいて 2026-10-21 に確認しました。対象は Ruff の D103 有無ルール と DOC501 例外の完全性ルール（--preview とルールの選択が必要）、pydoclint が対応するチェックとスタイル、interrogate のカバレッジに関するドキュメントです。機能は有効にしたルールと設定によって異なります。-- は、これらの情報源に該当するチェックの説明がないことを意味します。

pydoclint は、Google、NumPy、Sphinx の各スタイルで、引数、戻り値、yield、例外、クラス属性、型ヒントをチェックします。docvet の拡張機能だけでも 21 のルールがあり、Raises、Yields、Receives、Warns、Attributes、Examples、相互参照、パラメーターの整合性などが含まれます。有無（カバレッジメトリクス＋しきい値の適用）、鮮度（git diff/blame による古さの兆候）、griffe のレンダリング互換性、mkdocs のカバレッジを加えると、5 種類のチェックにわたる 32 のルールになります。ルール数はカタログ内の項目数を示すもので、ツール間で同等のカバレッジがあることを示すものではありません。

構造の整合性チェックでは、ドキュメントに記載された要素とコード構造を比較します。鮮度チェックでは、変更履歴を使ってレビューを提案します。コードが変更されても文章が無効になるとは限らず、コードと docstring を同時に編集しても、文章が誤ったままになることがあります。どちらも意味上の正しさを確立するものではありません。

クイックスタート | GitHub Action | Pre-commit | 設定 | AI エージェントとの連携 | ドキュメント

チェック項目

存在（有無）— 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 に指定したチェックで終了コードが 0 以外になります。指定されていないチェックは警告として扱われます。

fail-on に指定したチェックを実行できない場合（多くの場合、docvet[griffe] エクストラを指定せずに griffe を実行した場合）、設定したゲートの検証は完了しません。そのため、docvet は標準エラー出力に報告し、終了コード 1 で終了します。--format json を指定すると、run オブジェクトに status: "unavailable" と unavailable_checks 配列が出力され、問題が見つかったゲートと区別できます。代わりに警告を出して終了コード 0 にするには、fail-on-unavailable = false を設定するか、--no-fail-on-unavailable を渡します。ゲートの対象になっていないチェックが利用できない場合は、何も出力せずにスキップされます。ただし、ゲートの対象となる条件は 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

GitHub Actions のワークフローに docvet を追加すると、検出結果が 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 レンダリングチェックに特別な設定は必要ありません。このアクションは、固定するかどうかにかかわらず docvet[griffe] をインストールするため、checks 入力で選択できるすべてのチェックが利用可能です。1.7.0 より前の docvet リリースでは、このエクストラに上限が設定されていません。そのため、バージョンを固定しても、docvet のリリース時に検証されたバージョンではなく、その時点で公開されている Griffe がインストールされる点にご注意ください。

動作変更 — これにより、成功していたビルドが失敗することがあります。

以前のリリースでは通常の docvet をインストールしていたため、Griffe チェックはスキップされ、検出結果にも何も追加されませんでした。現在は実行されます。determine_run_outcome（src/docvet/reporting.py）は、fail-on に指定されたチェックで検出結果があると、直ちに終了コード 1 を返します。そのため、pyproject.toml の [tool.docvet] fail-on に griffe が含まれている場合、こちらで何も変更していなくても、ビルドは成功から失敗に変わります。このリポジトリの ci.yml にある docvet ジョブが、まさにこの影響を受けます。

これは新たな問題ではありません。これまでずっと問題のあった docstring に対して、チェックがようやく実行されたということです。成功状態に戻すには、Griffe の検出結果を修正するか、fail-on から griffe を削除してください。

AI エージェントとの統合

ツールごとの統合スニペットについては、AI エージェントとの統合ガイド全文をご覧ください。

AI コーディングのワークフローに docvet を追加します。以下を CLAUDE.md、.cursorrules、またはエージェントの設定に追加してください。

## 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カバレッジ指標を使って、docstring の不足をチェックします
docvet enrichmentdocstring セクションの不足をチェックします
docvet freshnessgit を使って、古くなっている可能性のある docstring を検出します
docvet freshness --mode driftgit blame を使って、古くなっている可能性がある箇所を確認します
docvet coveragemkdocs から見えないファイルを検出します
docvet griffemkdocs のレンダリング互換性をチェックします
docvet fix不足している docstring セクションのひな形を作成します
docvet fix --dry-runファイルを書き換えずに、ひな形の変更をプレビューします
docvet configソースの注釈付きで有効な設定を表示します
docvet lspリアルタイムのエディター診断用に LSP サーバーを起動します
docvet mcpAI エージェントとの統合用に MCP サーバーを起動します

より良い docstring で、より優れた AI を

AI コーディングエージェントは、コードの生成や変更時に docstring をコンテキストとして利用します。エージェントはコードを変更しても、docstring を古いままにすることがよくあります。また、調査によると、古いドキュメントや不正確なドキュメントは、ドキュメントがない場合よりも有害です。

2025 DORA レポートの言葉を借りると、「AI はチームを変えるのではなく、すでにあるものを増幅します。」AI による生産性と相関する唯一のシグナルはコード品質です。

docvet の鮮度ヒューリスティクスは、確認が必要な古い可能性のある箇所を検出し、エンリッチメントルールは、サポートされている docstring セクションとコード構造を照合します。CI、pre-commit フック、またはエージェントのツールチェーンで 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

コメント

Markdown 対応

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。