Intersphinx

This extension generates links to external Sphinx documentation objects. For this, it uses the external documentation’s auto-generated objects.inv file, which contain all navigable references of that Sphinx documentation.

Configuration

First, add the extension to your extensions variable:

conf.py

extensions = [
    ...
    'sphinx.ext.intersphinx'
]

As the official documentation explains, each external documentation to be used by intersphinx must be declared in the intersphinx_mapping config value. This can be done in the following ways:

conf.py

intersphinx_mapping = {
    # use default objects.inv (here: https:/example.url/objects.inv)
    'basic_external_doc': ('https:/example.url', None),
    # use custom objects file (here: https:/example.url/custom-inv.txt)
    'custom_objects_file_doc': ('https:/example.url', 'custom-inv.txt')
    # multiple objects files (iterated from left to right, use first valid one)
    # here: local objects file --(if not found)--> default
    'basic_with_local_objects_file_doc': ('https:/example.url', ('../local/objects.inv', None))
}

Each entry must contain a unique key (e.g. basic_external_doc, in the usage schema below referred to as invname), under which the external documentation can be referenced in external (see Usage) and a value, containing a tuple with the base URL of the hosted external documentation as the first item and a reference to at least one objects.inv file as the second item. By default, this objects file is automatically created during building the HTML and put into the build output’s root directory, e.g. build/html/objects.inv. In this case, the reference must be set to None (as for 'basic_external_doc' above).

Hint

The objects file stores all explicit and implicit reference targets of the project. See Inspect the objects.inv file to learn more about it.

Usage

If an external documentation is listed in intersphinx_mapping and the corresponding objects.inv file (or any specified custom files) is found, all the references inside it can be used for referencing from your local documentation in the following ways:

• As a fallback solution: if a reference target cannot be found in the local documentation, Sphinx searches for a map in any declared external documentation objects file, or

  Hint

  The intersphinx_disabled_reftypes config value controls, which non-external reference types are attempted to be resolved by intersphinx)

• explicitly by using the external role

Schema:

# Fallback method

## Standard domain
:reftype:`target`

## Non-standard domain
:domain:reftype:`target`

## Look specific external documentation only
:invname:domain:reftype:`target`

# Explicit method (using the external role)

## Standard domain
:external:reftype:`target`

## Non-standard domain
:external:domain:reftype:`target`

## Look specific external documentation only
:external+invname:domain:reftype:`target`

Examples:

For a label (:ref:)

:ref:`some_external_reference_target_label`
:external:ref:`some_external_reference_target_label`
:external+basic_external_doc:ref:`some_external_reference_target_label`

For a document (:doc:)

:doc:`some/external/document`
:external:doc:`some/external/document`
:external+basic_external_doc:doc:`some/external/document`

Important

The std:doc domain (documents referenced via the :doc: role) is, by default, deactivated in intersphinx (see intersphinx_disabled_reftypes), which means, Sphinx does not search for external documents when using just :doc:, but requires using the external role. To disable this restriction, define the intersphinx_disabled_reftypes in conf.py, making sure, std:doc is not listed, for example:

conf.py

intersphinx_disabled_reftypes = []

Hint

External reference links can also be renamed, just like internal references. For example:

:external:ref:`Create extension (custom role) <extend_sphinx_create_custom_role>`

Understanding domains

In Sphinx, in order to allow references to the same type of objects for different programming languages, for example Python and C++, Sphinx provides multiple domains, which must be prepended to the reference type: For example

:py:class:`Foo`

checks the current documentation and all external documentations listed under intersphinx_mapping (see above) for a matching Python class definition (py:class), like:

.. py:class:: Foo

   .. py:method:: quux()

General cross-reference types, such as :ref: or :doc: are part of the standard domain, abbreviated with std (see Inspect the objects.inv file). Reference types from the standard domain may skip the declaration of the domain, hence these two lines

:external:std:ref:`some_external_reference_target_label``
:external:ref:`some_external_reference_target_label`

behave exactly the same. References to all non-standard domains, for example the Python domain, must be explicitly mentioned:

This is OK

:external:py:class:`Foo`

This may not work!

:external:class:`Foo`

The only exception is, if the primary domain is set to that particular domain. For example:

conf.py

primary_domain = 'cpp'

then a C++ function could be abbreviated as

:external:method:`do_something`

instead of :external:cpp:method:`do_something` to reference to an external C++ function.

Hint

You may override the global default domain within a single RST file using the default-domain directive.

Inspect the objects.inv file

As mentioned, each Sphinx projects creates a objects.inv file during HTML build, which stores all explicit and implicit reference targets of the project.

It is stored in binary format, so to view all stored targets, use the sphinx.ext.intersphinx module to inspect its contents, for example:

$ python -m sphinx.ext.intersphinx build/html/objects.inv

The output shows each reference in a single line in the following pattern:

<domain>:<reference_type>
    <label_name_A> <name_A> : <document_path_A>
    <label_name_B> <name_B> : <document_path_B>

for example

std:doc
    howto/docker/index               Docker                  : howto/docker/index.html
    howto/docker/tricks              Docker Cheatsheet       : howto/docker/tricks.html
    howto/docker/troubleshoot        Troubleshooting         : howto/docker/troubleshoot.html
std:label
    /howto/docker/index.rst          Docker                  : howto/docker/index.html
    /howto/docker/index.rst#docker   Docker                  : howto/docker/index.html#docker
    /howto/docker/tricks.rst         Docker Cheatsheet       : howto/docker/tricks.html

The example, above shows a few references to documents (std:doc, cross-referenced via :doc:) and labels (std:label, cross-referenced via :ref:). Both are part of the standard domain, which is abbreviated with std.

Hint

All cross-reference targets belong to the standard domain.