Sphinx / rST: using configuration values in include statements?

Question

In my main sphinx project I am using include statements to pull content of files that are stored in another place on my disk.

.. include:: //path/to/other/docs/file.rst

Now I want to be able to set the base path in my conf.py once, and simply reference this in my include statements.

Is this possible and if so, how can I achieve this?

---

For future reference: I wrote a Sphinx extension that allows this, see: https://github.com/j0nes2k/sphinx-contrib-configurableinclude

Answer 1

You can't do that with vanilla Sphinx. An implementation of include directive seems to does not care any additional configuration option:

• sphinx.directives.other.Include.run()
• sphinx.environment.BuildEnvironment.relfn2path()

But you can implement and setup your own directive. Check out Writing a simple extension section of Developing extensions for Sphinx.

So the easiest way seems to overrides sphinx.directives.other.Include. (Actually, Sphinx's Include also overrode the standard include directive docutils.parsers.rst.directives.misc.Include for better and correct path interpreting.)