Logo

First steps

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

Getting started

  • Configuration File
  • Incoming Webhooks and Automation
  • Custom Domains and White Labeling
  • Versioned Documentation
  • Downloadable Documentation
  • Documentation Hosting Features
  • Server Side Search
  • Analytics
  • Preview Documentation from Pull Requests
  • Connecting Your VCS Account
  • Build Process
  • Badges
  • Site Support
  • Frequently Asked Questions

Step-by-step Guides

  • Sphinx & MkDocs Guides
    • Adding Custom CSS or JavaScript to Sphinx Documentation
    • Cross-referencing with Sphinx
    • Link to Other Projects’ Documentation With Intersphinx
      • Using Intersphinx
      • Intersphinx in Read the Docs
      • Intersphinx with private projects
    • Manage Translations
    • Building With Pre-1.0 Versions Of MkDocs
    • Sphinx PDFs with Unicode
    • Removing “Edit on …” Buttons from Documentation
    • Version Control System Integration
  • Read the Docs Guides
  • Read the Docs for Business Guides

Advanced features

  • Subprojects
  • Single Version Documentation
  • Localization of Documentation
  • User-defined Redirects
  • Automatic Redirects
  • Automation Rules
  • Public API

About Read the Docs

  • Contributing to Read the Docs
  • Developer documentation
  • Roadmap
  • Google Summer of Code
  • Code of Conduct
  • Security
  • Privacy Policy
  • Read the Docs Terms of Service
  • DMCA Takedown Policy
  • Policy for Abandoned 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
  • Read the Docs for Business
Read the Docs
  • »
  • Sphinx & MkDocs Guides »
  • Link to Other Projects’ Documentation With Intersphinx
  • Edit on GitHub

Link to Other Projects’ Documentation With Intersphinx¶

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 we 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>`

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 -msphinx.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 I Need Secrets (or Environment Variables) in my Build 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'),
}
Next Previous

© Copyright 2010-2021, Read the Docs, Inc & contributors. Revision db24ee1f.

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