sphinx.ext.intersphinx – Link to other projects’ documentation¶

New in version 0.5.

This extension can generate automatic links to the documentation of Python objects in other projects. This works as follows:

• Each Sphinx HTML build creates a file named objects.inv that contains a mapping from Python identifiers to URIs relative to the HTML set’s root.
• Projects using the Intersphinx extension can specify the location of such mapping files in the intersphinx_mapping config value. The mapping will then be used to resolve otherwise missing references to Python objects into links to the other documentation.
• By default, the mapping file is assumed to be at the same location as the rest of the documentation; however, the location of the mapping file can also be specified individually, e.g. if the docs should be buildable without Internet access.

To use intersphinx linking, add 'sphinx.ext.intersphinx' to your extensions config value, and use these new config values to activate linking:

intersphinx_mapping¶

A dictionary mapping URIs to either None or an URI. The keys are the base URI of the foreign Sphinx documentation sets and can be local paths or HTTP URIs. The values indicate where the inventory file can be found: they can be None (at the same location as the base URI) or another local or HTTP URI.

Relative local paths in the keys are taken as relative to the base of the built documentation, while relative local paths in the values are taken as relative to the source directory.

An example, to add links to modules and objects in the Python standard library documentation:

intersphinx_mapping = {'http://docs.python.org/dev': None}

This will download the corresponding objects.inv file from the Internet and generate links to the pages under the given URI. The downloaded inventory is cached in the Sphinx environment, so it must be redownloaded whenever you do a full rebuild.

A second example, showing the meaning of a non-None value:

intersphinx_mapping = {'http://docs.python.org/dev': 'python-inv.txt'}

This will read the inventory from python.inv in the source directory, but still generate links to the pages under http://docs.python.org/dev. It is up to you to update the inventory file as new objects are added to the Python documentation.

When fetching remote inventory files, proxy settings will be read from the $HTTP_PROXY environment variable.

intersphinx_cache_limit¶

The maximum number of days to cache remote inventories. The default is 5, meaning five days. Set this to a negative value to cache inventories for unlimited time.