Claude CodeでSphinxの文書をビルドする — sphinx-build -Wで警告を直させる
Claude CodeにSphinxの文書を書かせ、sphinx-build -Wの終了コードを完了条件にして警告を自分で直させる手順です。nitpickyとsuppress_warningsの扱い、Stop hookの例付きです。
Claude CodeにSphinxの文書を書かせるなら、sphinx-build -W の終了コードを完了条件にするのが手堅いです。-W(--fail-on-warning)は、ビルド中に警告が1件でも出ると終了ステータス1で終わらせるフラグです。人が目で探していた壊れた参照や目次の漏れが、Claude Codeが読んで直せる失敗に変わります。
Sphinxの警告は、通常ならビルドが完走して見過ごされます。ページを足したのに目次へ入れ忘れる、docstringの参照先が消える。HTMLは生成されるので、気づくのは公開後です。ここでは、-W を軸に、警告の範囲を広げる nitpicky、逆に絞る suppress_warnings、Claude Codeへ検証を渡す3つの場所を順に示します。
-W は何を失敗にするのか
sphinx-build -W は、ビルド中に出た警告をエラー扱いにします。公式のmanページの説明は「警告があれば終了ステータス1で終わる」です。
挙動はSphinx 8.1を境に変わりました(下の図)。--keep-going は8.1以降は常に有効で、オプションは互換性のために残っているだけです。古いSphinxも使うプロジェクトでは、--keep-going を付けたままでも害はありません。
-W の挙動(Sphinx 8.1の前後)
8.1より前
最初の警告でビルドが止まります。全件を一度に見るには --keep-going を併用します。
8.1以降
最後まで走り、警告があれば終了ステータス1です。Claude Codeに全件を1回で渡せます。
自己修正のループでは、この差が再ビルドの回数に響きます。手元のSphinxのバージョンは sphinx-build --version で確かめられます。
長い形のオプション名(--fail-on-warning など)は7.3で追加されました。それ以前の版でも短い -W は使えます。
ビルドコマンドの形を決める
検証に使う1本を、CLAUDE.mdにもhookにも同じ形で書くと、手元とCIで差が出ません。
sphinx-build -W -b html docs docs/_build/htmldocs がソースディレクトリ、docs/_build/html が出力先です。-b html はビルダー(出力形式)の指定で、省略するとHTMLになります。ソースディレクトリには conf.py が必要で、sphinx-quickstart でひな形を作れます。
-M のmake-modeを使う書き方もあります。
sphinx-build -M html docs docs/_build -W-M は最初に置く決まりで、出力先は <出力先>/html のように、ビルダー名のサブディレクトリになります。-b とは出力先の規則が違うため、コマンドを混ぜないでください。Claude Codeに「ビルドして」とだけ頼むと、make html と sphinx-build -b が混在しがちです。どちらか一方に決めて、CLAUDE.mdに書いておきます。
make html を選ぶ場合、-W はMakefileの SPHINXOPTS 変数で渡します。make html SPHINXOPTS="-W" のように書くか、環境変数 SPHINXOPTS に入れます。短縮変数 O でも同じです。Makefileを経由すると、-W が付いているかがコマンド行から見えなくなるため、完了条件には sphinx-build を直接呼ぶ形のほうが確実です。
警告をファイルにも残したいときは -w <ファイル> を足します。標準エラーに加えて指定のファイルへ書き出され、ANSI制御文字は7.3以降は除かれます。Claude Codeに「build-warnings.txt を読んで直して」と渡す形にすると、出力が長くても取りこぼしません。
警告の範囲を広げる — nitpicky
-W だけでは、Sphinxが既定で警告にしないものは素通りします。その代表が、参照先が見つからないケースです。
-n(--nitpicky)を付けるか、conf.py に nitpicky = True を書くと、参照先が解決できないものがすべて警告になります。新しいプロジェクトでは有効にすることが推奨されています。一時的に試したいときは、コマンドラインの -n が使えます。
# docs/conf.py
nitpicky = True
nitpick_ignore = {
("py:class", "numpy.ndarray"),
}既知の「見つからない参照」は、nitpick_ignore に (警告の種類, 対象) の組で並べて除外します。警告の種類にはドメイン名を含めます(py:class など)。正規表現で書きたいときは nitpick_ignore_regex を使い、文字列全体に一致させます。
ここに、Claude Codeを使うときの落とし穴があります。nitpickyを有効にしたあと、外部ライブラリの型が解決できない警告が大量に出ると、モデルは nitpick_ignore に足して黙らせる近道を選びがちです。除外の追加は、人が意図して行うものとして、CLAUDE.mdで線を引いておきます。
警告を黙らせる前に — suppress_warnings
逆向きの道具が suppress_warnings です。警告コードのリストを渡すと、該当する警告が出なくなります。
# docs/conf.py
suppress_warnings = ["autodoc.import_object"]どのコードを書けばよいかは、警告に付く種類の表示から分かります。show_warning_types は既定で True で、WARNING: [...] [index] や [toc.circular] のように、警告の末尾に種類が付きます。この設定は、suppress_warnings に入れる値を探すために使います。
既定の警告コードは、ref.python・toc.not_included・image.not_readable・i18n.not_readable など多数です。ref や toc のように先頭の1要素だけを書くと、その系統をまとめて除外します。広く黙らせるほど、-W で拾える範囲が狭まります。
autodocは、この表に自分の種類も足します。autodoc と autodoc.import_object です。モジュールのimportに失敗する環境(依存が入っていないなど)では、autodoc_mock_imports でそのモジュールを偽物に差し替える方法もあります。['django'] のようにトップレベルのパッケージ名だけを書けば、配下のimportもまとめて対象です。
ひとつ注意点があります。autodoc_warningiserror はimport中の警告の扱いを決める設定でしたが、Sphinx 8.1で --fail-on-warning が最初の警告で止まらなくなったため、効果がなくなりました。古い記事の設定をそのまま写さないでください。
-W を守る設定と緩める設定では、Claude Codeに任せる範囲が分かれます。
| 設定 | 向き | Claude Codeに任せる範囲 |
|---|---|---|
-W | 向き警告を失敗にする | Claude Codeに任せる範囲常に付ける |
nitpicky / -n | 向き警告の範囲を広げる | Claude Codeに任せる範囲有効化は任せてよい |
nitpick_ignore | 向き個別の参照を除外 | Claude Codeに任せる範囲人が決める |
suppress_warnings | 向き警告の系統を除外 | Claude Codeに任せる範囲人が決める |
Claude Codeへ検証を渡す3つの場所
ビルドの形と警告の方針が決まったら、Claude Codeに渡します。指示として渡す場所、確認なしの実行として渡す場所、強制として渡す場所の3つです。
CLAUDE.mdに完了条件を書く
Claude Codeは、CLAUDE.mdをセッションの開始時に読みます。文書プロジェクトでは、書き方の規約より先に「何をもって完了とするか」を置きます。
# ドキュメント作業のルール
- ビルドは `sphinx-build -W -b html docs docs/_build/html` に統一する
- 文書を追加・移動・改名したら、親の toctree も同時に更新する
- 作業の終わりに上のコマンドを実行し、終了コード 0 を確認する
- 警告を消すために `suppress_warnings` や `nitpick_ignore` を足さない。
原因のファイルを直す。除外が必要だと思ったら、理由を書いて人に確認する最後の1行が要です。除外の追加は短い近道ですが、警告の検出力を静かに下げます。禁止を明文化し、迷ったら人に聞く経路を残しておきます。
permissionsで再ビルドを確認なしにする
検証コマンドは何度も回ります。毎回承認を求められると、ループが人の手待ちで止まります。許可ルールは Bash(<コマンド>) の形で書き、* は空白を含む任意の文字列に一致します。
{
"permissions": {
"allow": [
"Bash(sphinx-build -W -b html docs docs/_build/html)",
"Bash(sphinx-build -W -n -b html docs docs/_build/html)"
]
}
}この内容は .claude/settings.json に置きます。* を使えば1行にまとめられますが、公式は、* をサブコマンドの後ろに置くことを勧めています。sphinx-build は引数だけで挙動が変わるので、ここでは使うコマンドをそのまま並べています。許可の範囲が広がるほど、意図しない出力先への書き込みが通りやすくなります。
Stop hookで強制する
CLAUDE.mdの指示は、守られないことがあります。確実に走らせたいなら、hookを使います。Stop は、Claude Codeが応答を終えた時点で動きます。ここで終了コード2を返すと、Claude Codeは作業を続け、標準エラーの内容を次の指示として受け取ります。
#!/bin/sh
# .claude/hooks/sphinx-strict.sh
input=$(cat)
# すでにhookの結果で続行中なら、同じ失敗で堂々巡りしない
echo "$input" | grep -q '"stop_hook_active": *true' && exit 0
out=$(sphinx-build -W -b html docs docs/_build/html 2>&1) || {
echo "$out" | tail -n 60 >&2
exit 2
}{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "sh .claude/hooks/sphinx-strict.sh",
"timeout": 300
}
]
}
]
}
}stop_hook_active は、すでにStop hookの結果で続行しているときに true になる入力項目です。公式は、解消しない条件で止め続けないために、この値を確かめるよう勧めています。上のスクリプトは続行中なら素通りさせるので、1回の失敗につき1回だけ再挑戦させる形です。
安全網もあります。Stop hookの続行が連続8回に達すると、Claude Codeは次のブロックを無効にしてターンを終えます。回数は、Claudeがツールを呼ぶたびに数え直され、CLAUDE_CODE_STOP_HOOK_BLOCK_CAP で上限を変えられます。
hookの書き方そのものはhooksの設定を一から試す入門にあります。テスト実行を同じ枠に載せる例はhooksでテストを自動実行する使い分けが扱っています。
警告を読んで直す順序
-W が失敗したら、Claude Codeには警告全件を渡します。直す順番は、警告の種類で決めると手戻りが減ります。
警告が出たときの切り分け
- Qdocutilsや構文の警告か?(見出しの階層、インデントなど)答えが次へ答えがはい
マークアップの書き方の問題です。該当ファイルの該当行を直します。
- Q目次(toctree)に関する警告か?答えが次へ答えがはい
文書が目次に載っていない、目次が循環している、といった構造の問題です。親の
toctreeを直します。読者に見せない文書ならexclude_patternsで除外します。 - Q参照(`:ref:` や `:doc:` など)が解決できない警告か?答えが次へ答えがはい
参照先のラベルや文書名を確かめます。文書を改名・移動していれば、リンク元の追従漏れです。
autodocのimport失敗は環境を確かめる
モジュールがimportできないと、そのAPIの節が空になります。依存のインストールか、autodoc_mock_imports の設定を確かめます。
直したあとは、-w で書き出した警告ファイルの行数を前後で比べさせると、減ったかどうかを確かめられます。
外部リンクの検査は別のビルダーで
-W が見るのは、ソース内の整合です。外部URLの死活までは見ません。その役割は、linkcheck ビルダーが担います。公式の説明では、外部リンクをすべて開こうとし、壊れたものとリダイレクトされたものを標準出力と出力先の output.txt に書きます。
sphinx-build -b linkcheck docs docs/_build/linkcheckネットワークに出るため、Stop hookには向きません。毎回の応答終了で外部サイトを叩くと、遅いうえに相手先の都合で失敗します。CIの定期ジョブや、Claude Codeに明示的に頼んだときだけ走らせる使い方が合います。設定では、待つ秒数を linkcheck_timeout(既定30秒)、検査から外すURLの正規表現を linkcheck_ignore で指定できます。
つまずきやすい点
-W が通っても、読みやすいとは限りません。検査の対象は、Sphinxが警告として出すものです。説明の正確さ、手順の抜け、スクリーンショットの古さは見ません。日本語の文章の校正は、textlintをhookで回す方法のような別の検査が受け持ちます。
拡張の非推奨警告が混ざることがあります。RemovedInSphinxXXXWarning のような警告は、使っている拡張が古い機能に頼っているサインです。拡張の作者へ報告する種類のもので、文書側では直せません。-W が失敗する原因が自分の文書でないときは、出力を切り分けます。PYTHONWARNINGS= を空にして実行すると、非推奨警告を出さずにビルドできます。
増分ビルドの範囲にも注意が要ります。Sphinxは既定で、新規または変更のあったソースだけを読み込んで解析します。全体を検査したいときは、-E(--fresh-env)で保存済みの環境を使わずに作り直します。-a は出力ファイルの書き直しだけで、ソースの再読込はしません。
並列ビルドは環境に依存します。-j auto でCPU数に合わせて並列化できますが、forkに対応する環境が前提で、Windowsは対象外です。実験的な機能という位置づけです。検証用のコマンドは、再現性を優先して並列にしないほうが無難です。
ビルドの出力先は巻き込まないようにします。docs/_build を .gitignore に入れ、Claude Codeが生成物をコミットしないようにしておきます。
まとめ
Sphinxの文書づくりでは、sphinx-build -W の終了コードを完了条件にすると、目次の漏れ・壊れた参照・autodocのimport失敗がビルドの失敗として表に出ます。Sphinx 8.1以降は全件が一度に出るので、Claude Codeは1回の出力でまとめて直せます。
見直す順序は、コマンドよりも先に「警告を黙らせる経路」です。suppress_warnings と nitpick_ignore の追加を人の判断に残し、CLAUDE.mdで明文化しておけば、-W の検出力は保たれます。同じ設計はMkDocsでも使え、build --strictで検証する手順と、Docusaurusのリンク切れ検査に並べると、警告を失敗に変える入口がツールごとにどう違うかが見えてきます。