Cross-referencing with Sphinx

When writing documentation you often need to link to other pages of your documentation, other sections of the current page, or sections from other pages.

An easy way is just to use the raw URL that Sphinx generates for each page/section. This works, but it has some disadvantages:

  • Links can change, so they are hard to maintain.

  • Links can be verbose and hard to read, so it is unclear what page/section they are linking to.

  • There is no easy way to link to specific sections like paragraphs, figures, or code blocks.

  • URL links only work for the html version of your documentation.

reStructuredText has a built-in way to linking to elements, and Sphinx extends this to make it even more powerful! Some advantages of using reStructuredText’s references:

  • Use a human-readable name of your choice, instead of a URL.

  • Portable between formats: html, PDF, ePub.

  • Sphinx will warn you of invalid references.

  • You can cross reference more than just pages and section headers.

This page describes some best-practices for cross-referencing with Sphinx.

Getting started

Explicit targets

Note

If you are not familiar with reStructuredText, check reStructuredText Primer for a quick introduction.

Cross referencing in Sphinx uses two components, references and targets.

  • references are pointers in your documentation to other parts of your documentation.

  • targets are where the references can point to.

You can manually create a target in any location of your documentation, allowing you to reference it from other pages. These are called explicit targets.

For example, one way of creating an explicit target for a section is:

.. _My target:

Explicit targets
~~~~~~~~~~~~~~~~

Then we can reference the section using `My target`_, that will be rendered as My target.

You can also add explicit targets before paragraphs (or any other part of a page).

Another example, here we add a target to a paragraph:

.. _target to paragraph:

An easy way is just to use the final link of the page/section.
This works, but it has some disadvantages:

Then we can reference it using `target to paragraph`_, that will be rendered as: target to paragraph.

The reference displays the name of the target by default, but we can use any text you want. For example: `my custom text <target to paragraph>`_, that will be rendered as: my custom text.

We can also create in-line targets within an element on your page, allowing you to, for example, reference text within a paragraph.

For example, an in-line target inside a paragraph:

We can also create _`in-line targets` within an element on your page,
allowing you to, for example, reference text *within* a paragraph.

Then we can reference it using `in-line targets`_, that will be rendered as: in-line targets.

Implicit targets

You may also reference sections by name without explicitly giving them one by using implicit targets.

When we create a section, reStructuredText will create a target with the title as the name. For example, to reference the previous section we can use `Explicit targets`_, that will be rendered as: Explicit targets.

Note

Footnotes and citations also create implicit targets.

Cross-referencing using roles

All targets that we have seen so far can be referenced only from the same page. Sphinx provides some roles that allows us to reference any explicit target from any page.

Note

Since Sphinx will make all explicit targets available globally, all targets must be unique.

You can see the complete list of cross-referencing roles at Cross-referencing syntax. Next, we will explore the most common ones.

The ref role

The ref role can be used to reference any explicit target. For example:

- :ref:`my target`.
- :ref:`Target to paragraph <target to paragraph>`.
- :ref:`Target inside a paragraph <in-line targets>`.

That will be rendered as:

The ref role also allow us to reference code blocks:

.. _target to code:

.. code-block:: python

   # Add the extension
   extensions = [
      'sphinx.ext.autosectionlabel',
   ]

   # Make sure the target is unique
   autosectionlabel_prefix_document = True

We can reference it using :ref:`code <target to code>`, that will be rendered as: code.

The doc role

The doc role allows us to link to a page instead of just a section. The target name can be relative to the page where the role exists, or relative to your documentation’s root folder (in both cases, you should omit the extension).

For example, to link to a page in the same directory as this one we can use:

- :doc:`intersphinx`
- :doc:`/guides/intersphinx`
- :doc:`Custom title </guides/intersphinx>`

That will be rendered as:

Tip

Using paths relative to your documentation root is recommended, so we avoid changing the target name if the page is moved.

The numref role

The numref role is used to reference numbered elements of your documentation. For example, tables and images.

To activate numbered references, add this to your conf.py file:

# Enable numref
numfig = True

Next, ensure that an object you would like to reference has an explicit target.

For example, we can create a target for the next image:

Logo

Fig. 5 Link me!

.. _target to image:

.. figure:: /img/logo.png
   :alt: Logo
   :align: center
   :width: 240px

   Link me!

Finally, reference it using :numref:`target to image`, that will be rendered as Fig. 5. Sphinx will enumerate the image automatically.

Automatically label sections

Manually adding an explicit target to each section and making sure is unique is a big task! Fortunately, Sphinx includes an extension to help us with that problem, autosectionlabel.

To activate the autosectionlabel extension, add this to your conf.py file:

# Add the extension
extensions = [
   'sphinx.ext.autosectionlabel',
]

# Make sure the target is unique
autosectionlabel_prefix_document = True

Sphinx will create explicit targets for all your sections, the name of target has the form {path/to/page}:{title-of-section}.

For example, we can reference the previous section using:

- :ref:`guides/cross-referencing-with-sphinx:explicit targets`.
- :ref:`Custom title <guides/cross-referencing-with-sphinx:explicit targets>`.

That will be rendered as:

Invalid targets

If we reference an invalid or undefined target Sphinx will warn us. You can use the -W option when building your docs to fail the build if there are any invalid references. On Read the Docs you can use the sphinx.fail_on_warning option.

Finding the reference name

When you build your documentation, Sphinx will generate an inventory of all explicit and implicit links called objects.inv. You can list all of these targets to explore what is available for you to reference.

List all targets for built documentation with:

python -m sphinx.ext.intersphinx <link>

Where <link> is either a URL or a local path that points to your inventory file (usually in _build/html/objects.inv). For example, to see all targets from the Read the Docs documentation:

python -m sphinx.ext.intersphinx https://docs.readthedocs.io/en/stable/objects.inv

Cross-referencing targets in other documentation sites

You can reference to docs outside your project too! See Link to Other Projects’ Documentation With Intersphinx.