Sphinx拡張自作で、設定値を追加したい場合はどうする？

Today I Learnedです。
Sphinx拡張¹開発をしていて、ユーザがconf.py中の変数で設定できるようにしたいと思いました。

• Sphinxアプリケーションのadd_config_value()メソッドで定義
• Builderのconfig属性でアクセス
  • SphinxアプリケーションやTranslatorはBuilderを持つ

目次

設定できるSphinx拡張を観察：sphinx-revealjs

やり方をパクるために、お世話になっている²sphinx-revealjsをのぞきます。
https://sphinx-revealjs.readthedocs.io/en/latest/configurations/
revealjs_static_pathなどがあります。

conf.pyにて³

revealjs_static_path = ["_static"]

conf.pyで変数に代入することで設定します。

実現方法は
https://github.com/attakei/sphinx-revealjs/blob/v3.0.2/sphinx_revealjs/__init__.py#L124

app.add_config_value("revealjs_static_path", [], True)

Sphinxの設定値（現時点の理解）

設定値の宣言

Sphinxアプリケーションのadd_config_value()メソッド
https://www.sphinx-doc.org/ja/master/extdev/appapi.html#sphinx.application.Sphinx.add_config_value

sphinx-revealjsの例だと

• revealjs_static_pathという名前の設定値
• デフォルト値は[]（空のリスト）
• rebuild引数Trueは"env"の意味と思われます

  • 設定を変更してからビルドをかけると、環境全体が再ビルドされます。

設定値へのアクセス

sphinx-revealjsを見たところ、Builderの持つconfig属性でアクセスしていました。

• Builderはself.config.revealjs_static_path
  • https://github.com/attakei/sphinx-revealjs/blob/v3.0.2/sphinx_revealjs/builders.py#L64-L66
• builder.config.revealjs_static_pathで参照
  • https://github.com/attakei/sphinx-revealjs/blob/v3.0.2/sphinx_revealjs/ext/footnotes/__init__.py#L17
  • Sphinxアプリケーションはbuilderを持つ

Builderは出力をビルドしますが、出力フォーマット変換はTranslatorに委譲します⁴。
TranslatorはBuilder（への参照）を持つので、Translatorからはself.builder.config.XXXのようになりました。

---

1. setup関数を持ったモジュールです。↩
2. 一例 ↩
3. 登壇資料の公開リポジトリより https://github.com/ftnext/2024-slides/blob/20f9762faa2c89c5723882a033a8cb7c33b0d4f6/source/conf.py#L42↩
4. この記事の注では再掲ですが、こちらをどうぞ ↩