How to link to other documentation projects with Intersphinx

This section shows you how to maintain references to named sections of other external Sphinx projects.

You may be familiar with using the :ref: role to link to any location of your docs. It helps you to keep all links within your docs up to date and warns you if a reference target moves or changes so you can ensure that your docs don’t have broken cross-references.

Sometimes you may need to link to a specific section of another project’s documentation. While you could just hyperlink directly, there is a better way. Intersphinx allows you to use all cross-reference roles from Sphinx with objects in other projects. That is, you could use the :ref: role to link to sections of other documentation projects. Sphinx will ensure that your cross-references to the other project exist and will raise a warning if they are deleted or changed so you can keep your docs up to date.

If you are publishing several Sphinx projects together using Read the Docs’ subprojects (see Subprojects), you should use Intersphinx to reference your subprojects from other projects.

Note

You can also use Sphinx’s linkcheck builder to check for broken links. By default it will also check the validity of #anchors in links.

sphinx-build -b linkcheck . _build/linkcheck

See all the options for the linkcheck builder.

Using Intersphinx

To use Intersphinx you need to add it to the list of extensions in your conf.py file.

# conf.py file

extensions = [
    "sphinx.ext.intersphinx",
]

And use the intersphinx_mapping configuration to indicate the name and link of the projects you want to use.

# conf.py file

intersphinx_mapping = {
    "sphinx": ("https://www.sphinx-doc.org/en/master/", None),
}

# We recommend adding the following config value.
# Sphinx defaults to automatically resolve *unresolved* labels using all your Intersphinx mappings.
# This behavior has unintended side-effects, namely that documentations local references can
# suddenly resolve to an external location.
# See also:
# https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html#confval-intersphinx_disabled_reftypes
intersphinx_disabled_reftypes = ["*"]

Note

If you are using Read the Docs’ subprojects, you also need to enable the Intersphinx extension on each of the subprojects. For each subproject, you need to add the main project and all the other subprojects to intersphinx_mapping.

Now you can use the sphinx name with a cross-reference role:

reStructuredTextMyST (Markdown)

- :ref:`sphinx:ref-role`
- :ref:`:ref: role <sphinx:ref-role>`
- :doc:`sphinx:usage/extensions/intersphinx`
- :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`

Result:

• Cross-referencing arbitrary locations

• :ref: role

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

• Intersphinx

Note

You can get the targets used in Intersphinx by inspecting the source file of the project or using this utility provided by Intersphinx:

python -m sphinx.ext.intersphinx https://www.sphinx-doc.org/en/master/objects.inv

Intersphinx in Read the Docs

You can use Intersphinx to link to subprojects, translations, another version or any other project hosted in Read the Docs. For example:

# conf.py file

intersphinx_mapping = {
    # Links to "v2" version of the "docs" project.
    "docs-v2": ("https://docs.readthedocs.io/en/v2", None),
    # Links to the French translation of the "docs" project.
    "docs-fr": ("https://docs.readthedocs.io/fr/latest", None),
    # Links to the "apis" subproject of the "docs" project.
    "sub-apis": ("https://docs.readthedocs.io/projects/apis/en/latest", None),
}

Intersphinx with private projects

If you are using Business hosting, Intersphinx will not be able to fetch the inventory file from private docs.

Intersphinx supports URLs with Basic Authorization, which Read the Docs supports using a token. You need to generate a token for each project you want to use with Intersphinx.

1. Go the project you want to use with Intersphinx

2. Click Admin > Sharing

3. Select HTTP Header Token

4. Set an expiration date long enough to use the token when building your project

5. Click on Share!.

Now we can add the link to the private project with the token like:

# conf.py file

intersphinx_mapping = {
    # Links to a private project named "docs"
    "docs": (
        "https://<token-for-docs>:@readthedocs-docs.readthedocs-hosted.com/en/latest",
        None,
    ),
    # Links to the private French translation of the "docs" project
    "docs": (
        "https://<token-for-fr-translation>:@readthedocs-docs.readthedocs-hosted.com/fr/latest",
        None,
    ),
    # Links to the private "apis" subproject of the "docs" project
    "docs": (
        "https://<token-for-apis>:@readthedocs-docs.readthedocs-hosted.com/projects/apis/en/latest",
        None,
    ),
}

Note

Sphinx will strip the token from the URLs when generating the links.

You can use your tokens with environment variables, so you don’t have to hard code them in your conf.py file. See Environment variable overview to use environment variables inside Read the Docs.

For example, if you create an environment variable named RTD_TOKEN_DOCS with the token from the “docs” project. You can use it like this:

# conf.py file

import os

RTD_TOKEN_DOCS = os.environ.get("RTD_TOKEN_DOCS")

intersphinx_mapping = {
    # Links to a private project named "docs"
    "docs": (
        f"https://{RTD_TOKEN_DOCS}:@readthedocs-docs.readthedocs-hosted.com/en/latest",
        None,
    ),
}

Note

Another way of using Intersphinx with private projects is to download the inventory file and keep it in sync when the project changes. The inventory file is by default located at objects.inv, for example https://readthedocs-docs.readthedocs-hosted.com/en/latest/objects.inv.

# conf.py file

intersphinx_mapping = {
    # Links to a private project named "docs" using a local inventory file.
    "docs": (
        "https://readthedocs-docs.readthedocs-hosted.com/en/latest",
        "path/to/local/objects.inv",
    ),
}