.. highlight:: rst

:mod:sphinx.ext.ifconfig -- Include content based on configuration

.. module:: sphinx.ext.ifconfig :synopsis: Include documentation content based on configuration values.

This extension is quite simple, and features only one directive:

.. warning::

This directive is designed to control only content of document. It could not control sections, labels and so on.

.. rst:directive:: ifconfig

Include content of the directive only if the Python expression given as an argument is True, evaluated in the namespace of the project's configuration (that is, all registered variables from :file:conf.py are available).

For example, one could write ::

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

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

To make a custom config value known to Sphinx, use :func:~sphinx.application.Sphinx.add_config_value in the setup function in :file:conf.py, e.g.::

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

The second argument is the default value, the third should always be 'env' for such values (it selects if Sphinx re-reads the documents if the value changes).