Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Snippet of a Sphinx extension to allow global configuration of include paths via
import sys
from docutils.parsers.rst import Directive
from docutils import nodes
# Usage:
# add this to
# configurableinclude_paths = { 'module1': '/var/repositories/module1' }
# in your template, you can use:
# .. include_from_config:: module1 /docs/databaseaccess.rst
# This example should resolve to the full path '/var/repositories/module1/docs/databaseaccess.rst'
def setup(app):
app.add_config_value('configurableinclude_paths', {}, False)
app.add_directive('include_from_config', ConfigurableInclude)
class ConfigurableInclude(Directive):
required_arguments = 2
optional_arguments = 0
def run(self):
paths = self.state.document.settings.env.config.configurableinclude_paths
full_filepath = paths[self.arguments[0]] + self.arguments[1]
with open(full_filepath, 'r') as myfile:
text =
retnode = nodes.Text(text)
return [retnode]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment