how to set a custom config value for sphinx in conf.py? (e.g., for sphinx.ext.ifconfig)

Question

[I split the original question into two after more testing and research]

I defined my own configuration value in conf.py and wrote a minimal extension to make it visible from rst files.

in conf.py:

sys.path.insert(0, os.path.abspath('.'))
extensions = ['sphinx.ext.ifconfig', 'myExt']
testlevel = 2

in a local myExt.py:

def setup(app):
   app.add_config_value('testlevel', '', True)

This works just fine; test.rst includes:

.. ifconfig:: testlevel == 2

    Hurray, it seems to work

According to the doc of sphinx.ext.ifconfig, it seems possible to call *app.add_config_value* directly from conf.py. Can anyone tell me how to do this?

Answer 1

Two things to note here:

1. First, the conf.py file is just a python file. The only thing special about it is that Sphinx specifically looks for it and imports it. You can do anything in this file you could do in a normal python file.
2. Second, the conf.py file can itself be an extension. In other words, it can have a setup function that should work the same way as one in an extension. So if you copy the contents of your extension (myExt.py) into the conf.py file, it should Just Work (tm).