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

This config value contains the locations and names of other projects that should be linked to in this documentation.

Relative local paths for target locations are taken as relative to the base of the built documentation, while relative local paths for inventory locations are taken as relative to the source directory.

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

Old format for this config value

This is the format used before Sphinx 1.0. It is still recognized.

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.

New format for this config value

New in version 1.0.

A dictionary mapping unique identifiers to a tuple (target, inventory). Each target is the base URI of a foreign Sphinx documentation set and can be a local path or an HTTP URI. The inventory indicates where the inventory file can be found: it can be None (at the same location as the base URI) or another local or HTTP URI.

The unique identifier can be used to prefix cross-reference targets, so that it is clear which intersphinx set the target belongs to. A link like :ref:`comparison manual <python:comparisons>` will link to the label “comparisons” in the doc set “python”, if it exists.

Example

To add links to modules and objects in the Python standard library documentation, use:

intersphinx_mapping = {'python': ('http://docs.python.org/3.2', 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 of the second tuple item:

intersphinx_mapping = {'python': ('http://docs.python.org/3.2',
                                  'python-inv.txt')}

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