Snippet of a Sphinx extension to allow global configuration of include paths via conf.py.

configurableinclude.py

import sys

from docutils.parsers.rst import Directive
from docutils import nodes

# Usage: 
# add this to conf.py:
# 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 = myfile.read()

        retnode = nodes.Text(text)
        return [retnode]