How to cross-reference to other pages from documentation¶

Note

This page was written in the style of a How-to Guide according to The Diátaxis Framework.

This guide shows how to reference to other pages in the documentation.

Warning

Actual cross-referencing is only possible with .rst files. If you are trying to cross-reference from a Jupyter notebook (.ipynb), you are actually linking to an external page, and therefore you should check How to add external links instead.

Pre-requisites¶

This guide assumes your project already has a working Sphinx documentation project in a folder called docs and the recommended folder structure. If you don’t have it, you can set it up with sphinx-quickstart following the tutorial Create a New Documentation Project.

Add the links¶

There are several types of pages that can be referenced:

Module pages
Function pages
Class pages
Method pages
Attribute pages
Pages from other documentation projects

Module pages¶

If the page to which you want to link corresponds to a module, you should use :mod:`your_module`. An example of Qiskit module is qiskit.visualization and the link can be written as:

:mod:`qiskit.visualization`

Function pages¶

If you want to link to a function page, you need to use :func:`your_function`. For example, you can link to the qiskit.visualization.circuit_drawer() by writing:

:func:`qiskit.visualization.circuit_drawer`

Class pages¶

In order to link to a class page, you should use :class:`your_class`. As an example, you can link to qiskit.circuit.QuantumCircuit by writing:

:class:`qiskit.circuit.QuantumCircuit`

Method pages¶

If your objective is to link the page of a method, you can use :meth:`your_method`. For example, to link to the qiskit.circuit.QuantumCircuit.draw() method if you write:

:meth:`qiskit.circuit.QuantumCircuit.draw`

Attribute pages¶

If you want to link to an attribute page, you should use :attr:`your_attribute`. You can link, for example, to qiskit.circuit.QuantumCircuit.parameters by writing:

:attr:`qiskit.circuit.QuantumCircuit.parameters`

Pages from other documentation projects¶

You can also use practically the same syntax to link to pages from other documentation projects. For this to work you need to add sphinx.ext.intersphinx to the extensions variable of your docs/conf.py.

After that, you’d need to create a new variable called intersphinx_mapping in your docs/conf.py. This variable has to be a dictionary whose keys are the name of the other projects (or any desired shortcut) and whose values are tuples that include the HTML page of the corresponding documentation and the object inventory. If the inventory is set to None, the

The basic syntax is then:

intersphinx_mapping = {"package": ("package_url", None)}

For example, if you want to add Qiskit’s and Sphinx’s documentation you can write this:

intersphinx_mapping = {
    "qiskit": ("https://docs.quantum.ibm.com/api/qiskit/", None),
    "sphinx": ("https://www.sphinx-doc.org/en/master/", None)
}

Once you have set the intersphinx_mapping, you can link to any sphinx:roles like :mod:, :func: or :class: in the same way as the previous sections, that is, :role:`name`.

However, if you want to make sure you are taking the object from the documentation of a specific package, the name of the object has to be preceded by that of the project that you set in intersphinx_mapping, followed by a colon :. So the syntax is:

:role:`package:name`

For example, to link to qiskit.circuit.QuantumCircuit you can write both :class:`qiskit.circuit.QuantumCircuit` or :class:`qiskit:qiskit.circuit.QuantumCircuit. In this case it doesn’t matter because there’s only one class with this name.

Note

Strictly speaking, what you are doing with intersphinx is linking to external pages but with the cross-reference syntax. For more information about linking to external pages, check How to add external links.

Shorten the links¶

You can shorten the links if you add ~ just before the name of your object (:obj:`~your_object`). For example, QuantumCircuit is shorter than qiskit.circuit.QuantumCircuit. This last sentence is written as:

For example, :class:`~qiskit.circuit.QuantumCircuit` is shorter than :class:`qiskit.circuit.QuantumCircuit`.

Shorten the reference¶

It’s not always necessary to specify the full name of your object when writing the reference. For example, you can write :class:`.QuantumCircuit` instead of :class:`qiskit.circuit.QuantumCircuit` to link to QuantumCircuit if no other class from any module is called QuantumCircuit. If there is another class with the same name, you will get a warning from Sphinx. You can also set any title you want for your links by using the following syntax: :role:`title <name>`. For example, you can add this link by writing:

:class:`this link <qiskit.circuit.QuantumCircuit>`