1.. highlight:: rest
2
3:mod:`sphinx.ext.ifconfig` -- Include content based on configuration
4====================================================================
5
6.. module:: sphinx.ext.ifconfig
7   :synopsis: Include documentation content based on configuration values.
8
9This extension is quite simple, and features only one directive:
10
11.. warning::
12
13   This directive is designed to control only content of document.  It could
14   not control sections, labels and so on.
15
16.. rst:directive:: ifconfig
17
18   Include content of the directive only if the Python expression given as an
19   argument is ``True``, evaluated in the namespace of the project's
20   configuration (that is, all registered variables from :file:`conf.py` are
21   available).
22
23   For example, one could write ::
24
25      .. ifconfig:: releaselevel in ('alpha', 'beta', 'rc')
26
27         This stuff is only included in the built docs for unstable versions.
28
29   To make a custom config value known to Sphinx, use
30   :func:`~sphinx.application.Sphinx.add_config_value` in the setup function in
31   :file:`conf.py`, e.g.::
32
33      def setup(app):
34          app.add_config_value('releaselevel', '', 'env')
35
36   The second argument is the default value, the third should always be
37   ``'env'`` for such values (it selects if Sphinx re-reads the documents if the
38   value changes).
39