nikkie-ftnextの日記

イベントレポートや読書メモを発信

Sphinxのビルド時に、受け入れるwarning以外が出力されたら、ビルドを異常終了する

Sphinx

はじめに

七尾百合子さん、お誕生日 6日目 おめでとうございます！ nikkieです。

発表資料はSphinx（sphinx-revealjs）で作っている私ですが、リリースビルドで想定外のwarningがあったら1そこで止められると気づきました。

目次

できたもの：発表資料をビルドしてリリースするパイプラインを落とす

発表資料はGitHub ActionsでGitHub Pagesとして公開しています。
GitHub Actionsではsphinx-buildを実行し、その結果をGitHub Pages用ブランチにpushします。

sphinx-buildに--fail-on-warningを指定して2、warningがあったらビルドを異常終了するようにしました。
これにより、不完全な資料がGitHub Pagesとして公開されることを防げます。

しかし、実はやむなく受け入れているwarningもあります。
例えば1リポジトリでディレクトリを切って複数のスライドを公開していると、ビルドはされますが、全体で1つのドキュメントとしては参照されないので[toc.not_included]が指摘されます。
受け入れるwarningは、conf.pyのsuppress_warningsに記載しました3。

suppress_warnings = ["toc.not_included"]

このコミットが本記事の結論です！

sphinx-buildの--fail-on-warningと--exception-on-warning

ヘルプを見たときに違いが分からなかったのがこの2つのフラグ。

ドキュメントによると

ロギングのレベルでいうと、errorレベルとcriticalレベルの違いのような感じでしょうか

--exception-on-warningと違って、--fail-on-warningはsuppress_warningsで動きを変えられます。
https://www.sphinx-doc.org/ja/master/usage/configuration.html#confval-suppress_warnings

  • suppress_warningsに指定されたwarningは、抑制されるのでwarningとして出ません（なのでerrorに変わることもありません）
  • 指定していないwarningは、--fail-on-warningによってerrorに変わります。

今回の場合[toc.not_included]は受け入れるのでerrorとして扱う必要がありませんが、他のtypeのwarningはerrorとして扱ってほしいのです

脱線：--exception-on-warningはなぜ登場した？

初見では紛らわしいと感じたので少し調べました。
上記のリンク先には「Added in version 8.1.」とあります

https://www.sphinx-doc.org/en/master/changes/8.1.html#features-added

#12743: Add sphinx-build --exception-on-warning, to raise an exception when warnings are emitted during the build.

Currently, using --fail-on-warnings gives a fairly hard to understand traceback (略) and means that on minor errors that are easily fixed, the entire build must be restarted, perhaps multiple times to fix errors incrementally.

--fail-on-warning（と--keep-going）を使うのが分かりづらかったので、ここで改善されたようです

（2025/03/24 この記事内のtypo修正。pull requestでは--fail-on-warningsですが、ドキュメントやヘルプメッセージからsは誤りですね）

終わりに

Sphinxでsuppress_warningsを使って特定のtypeのwarningを受け入れ、それ以外は--fail-on-warningでビルドを異常終了させられます！

先日の記事で取り上げたwarningのtype追加のおかげで、ピンポイントでsuppress_warningsに指定できるようになり、今回取り上げた知見が成立したように思われます

  1. 例えばreSTのマークアップの不備でwarningが出ることがあります↩
  2. https://github.com/ftnext/2025-slides/blob/11679f4eed21b29825dcead259860591aa79fd0c/Makefile#L10↩
  3. https://github.com/ftnext/2025-slides/blob/11679f4eed21b29825dcead259860591aa79fd0c/source/conf.py#L32↩