sphinx.ext.ifconfig -- 設定にしたがってコンテンツをON/OFFする

この拡張はきわめてシンプルです。ディレクティブもひとつだけ追加されます。

警告

このディレクティブはドキュメントの文面を制御するようにデザインされています。セクションやラベルは制御できません。

.. ifconfig::

引数として与えられているPythonの式が、プロジェクトの設定ファイルの名前空間の中で評価されたときに、Trueとなった場合のみ、指定されたコンテンツをドキュメントの中に追加します。 conf.py で定義されたすべての変数を使用可能です。

たとえば、以下のようなディレクティブを書くことができます:

.. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')

   This stuff is only included in the built docs for unstable versions.

もしも、カスタムの設定値を追加したい場合には、 conf.py ファイルの中のsetup関数の中で、 add_config_value() を使用すると行えます:

def setup(app):
    app.add_config_value('releaselevel', '', 'env')

2つめの引数はデフォルト値です。3つ目のパラメータはこのケースについては常にTrueにしてください。このパラメータは、設定値が変更された場合に、ドキュメントを再読み込みするかどうかという動作を選択するのに使用します。