Referring to doctrees in other projects

The rstgen.sphinxconf.interproject module is a utility to install the doctrees of all (or some) other atelier projects into your intersphinx_mapping configuration setting.

Usage

Add the following lines to your conf.py file:

from rstgen.sphinxconf import interproject
interproject.configure(globals())  # all projects

Or:

from rstgen.sphinxconf import interproject
interproject.configure(globals(), 'package1 package2', foo=("http://foo.com", filename))  # some projects

The configure() function accepts up to two positional arguments:

The first argument is the global namespace of your conf.py file into which the intersphinx_mapping should be defined. If you defined that name before calling configure(), that value will be overwritten. You may manually add more mappings to it after calling configure().

The second argument is optional and specifies a list of importable python module names or a string with a space-separated list thereof. If no second argument is given, all projects that come after the current project (according to the sort order defined in The config.py file) are added.

You can also add pure documentation projects (i.e. which don’t define a Python module) by specifying additional keyword arguments. Each keyword maps a project nickname to a tuple of (URI, filename). That tuple is just the default value to use when there is no project with that nickname in the projects list defined in ~/.atelier/config.py file.

Each of these projects must adhere to the convention of having two attributes doc_trees and intersphinx_urls either in their main module or in their tasks.py. Each doctree having a corresponding url in intersphinx_urls will be added to the intersphinx mapping.

ATELIER_IGNORE_LOCAL_BUILDS

If this environment variable is set to “yes”, the intersphinx mapping will ignore local data in the doctree builds of intersphinx projects. This can be useful to simulate behavior in an isolated testing environment.

intersphinx_mapping

A Sphinx setting in the conf.py of a doctree. See Sphinx docs