conf.pyにiniファイルから設定を読み込む

Sphinxの設定をconf.pyの外に書いておきたい場合があります。例えばiniやyamlに定義した値を読み込みたい場合はconf.pyに以下のように記載します。

conf.py

Sphinxはconf.pyを読み込むときに以下の順番で処理します。

  1. conf.pyをexecfile()相当の処理でSphinx内にロードする
  2. ロードした設定値をSphinx内のapp.config._raw_configに保存する
  3. conf.pyにsetup()があればこの関数を呼び出す
  4. app.config._raw_configからapp.configに値を移す

以下に2つの方法を紹介しますが、それぞれ処理のタイミングが異なります。

方法1

conf.pyの読み込み時に値を設定する方法です。(前述の処理1)

conf.py:

#...
#...既存の設定
#...
release = '1.0'
version = '1.0'

# iniを読み込む処理
from ConfigParser import SafeConfigParser
conf = SafeConfigParser()
conf.read('conf.ini')
for key, value in conf.items('sphinx'):
    exec("%s = %r" % (key, value))

exec()関数を使うところに抵抗があります。

方法2

conf.pyのsetup()関数で、確定直前の設定値を上書きする方法です。(前述の処理3)

conf.py:

#...
#...既存の設定
#...
release = '1.0'
version = '1.0'

def setup(app):
    # iniを読み込む処理
    from ConfigParser import SafeConfigParser
    conf = SafeConfigParser()
    conf.read(os.path.join(os.path.dirname(os.path.abspath(__file__)), 'conf.ini'))
    for key, value in conf.items('sphinx'):
        app.config._raw_config[key] = value

Sphinxの内部変数を書き換えるため、将来のバージョンアップで動作しなくなる可能性があります。

動作確認

以下のような conf.ini, index.rst を書いて確認します。

conf.ini:

[sphinx]
release = foo
version = bar

index.rst:

Welcome to conf.py test
=========================

:release: |release|
:version: |version|

make textすると以下の内容のindex.txtが出力されました:

Welcome to conf.py test
***********************

release:
   foo

version:
   bar