Logo

First steps

  • Read the Docs tutorial
  • Getting Started with Sphinx
  • Getting Started with MkDocs
  • Importing Your Documentation
  • Choosing Between Our Two Platforms

Features

  • Main Features
  • Configuration File
  • VCS Integrations
  • Custom Domains
  • Versioned Documentation
  • Downloadable Documentation
  • Documentation Hosting Features
  • Server Side Search
  • Traffic Analytics
  • Preview Documentation from Pull Requests
  • Build Notifications and Webhooks
  • Security log and auditing
  • Connecting Your VCS Account
  • Build process
  • Build customization
  • Build troubleshooting
  • Environment Variables
  • Status Badges
  • Site Support
  • Frequently Asked Questions

How-to Guides

  • Guides for documentation authors
    • Cross-referencing with Sphinx
    • Link to external projects (Intersphinx)
      • Using Intersphinx
      • Intersphinx in Read the Docs
      • Intersphinx with private projects
    • How to use Jupyter notebooks in Sphinx
    • Migrate from rST to MyST
  • Guides for project administrators
  • Guides for developers and designers
  • Read the Docs for Science
  • Example projects

Advanced features

  • Subprojects
  • Single Version Documentation
  • Flyout Menu
  • Feature Flags
  • Localization of Documentation
  • User-defined Redirects
  • Automatic Redirects
  • Automation Rules
  • Canonical URLs
  • Public API

Read the Docs for Business

  • Read the Docs for Business
  • Organizations
  • Project Privacy Level
  • Sharing
  • Single Sign-On
  • How to manage your Read the Docs for Business subscription

About Read the Docs

  • Security
  • DMCA Takedown Policy
  • Policy for Abandoned Projects
  • Policy for Unofficial and Unmaintained Projects
  • Changelog
  • About Read the Docs
  • Read the Docs Team
  • Read the Docs Open Source Philosophy
  • The Story of Read the Docs
  • Advertising
  • Sponsors of Read the Docs
  • Legal Documents and Policies
  • Developer Documentation
  • Glossary
  • Google Summer of Code
Read the Docs user documentation
  • Guides for documentation authors
  • How to Link to Other Documentation Projects With Intersphinx
  • Edit on GitHub

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.

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),
}

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

- :ref:`sphinx:ref-role`
- :ref:`:ref: role <sphinx:ref-role>`
- :doc:`sphinx:usage/extensions/intersphinx`
- :doc:`Intersphinx <sphinx:usage/extensions/intersphinx>`
- {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 Read the Docs for Business, 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 Variables 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",
    ),
}
Previous Next

© Copyright Read the Docs, Inc & contributors. Revision 5ab0da07.

Built with Sphinx using a theme provided by Read the Docs.
Read the Docs v: stable
Versions
latest
stable
diataxis-main
Downloads
pdf
html
epub
On Read the Docs
Project Home
Builds