Source

sphinx / sphinx / addons / ifconfig.py

Full commit
# -*- coding: utf-8 -*-
"""
    sphinx.addons.ifconfig
    ~~~~~~~~~~~~~~~~~~~~~~

    Provides the ``ifconfig`` directive that allows to write documentation
    that is included depending on configuration variables.

    Usage::

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

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

    The argument for ``ifconfig`` is a plain Python expression, evaluated in the
    namespace of the project configuration (that is, all variables from ``conf.py``
    are available.)

    :copyright: 2008 by Georg Brandl.
    :license: BSD.
"""

from docutils import nodes


class ifconfig(nodes.Element): pass


def ifconfig_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    node = ifconfig()
    node['expr'] = arguments[0]
    state.nested_parse(content, content_offset, node)
    return [node]


def process_ifconfig_nodes(app, doctree, docname):
    ns = app.config.__dict__.copy()
    ns['builder'] = app.builder.name
    for node in doctree.traverse(ifconfig):
        if not eval(node['expr'], ns):
            node.replace_self([])
        else:
            node.replace_self(node.children)


def setup(app):
    app.add_node(ifconfig)
    app.add_directive('ifconfig', ifconfig_directive, 1, (1, 0, 1))
    app.connect('doctree-resolved', process_ifconfig_nodes)