Cross references

Hyperlink text

There are different ways to create a link.

Citation style `link 1`_. .. _link 1: https://example.com/	Citation style link 1.
Inline 1 `link 2 <https://example.com/>`_.	Inline 1 link 2.
Inline 2 `<https://example.com/>`_.	Inline 2 https://example.com/.
Inline and citation combined `link 3 <my link_>`_. .. _my link: https://example.com/	Inline and citation combined link 3.
Sphinx style https://example.com/	Sphinx style https://example.com/

Anonymous hyperlinks

Anonymous hyperlinks allow to circumvent warnings due to duplicated target names. They are formed using 2 underscores (__) instead of one

`anonymous link 1 <https://example.com/>`__	anonymous link 1
`anonymous target 2`__ .. __: https://example.com/	anonymous target 2
`anonymous target 3`__ __ https://example.com/	anonymous target 3

Note

The order of anonymous references and target is important.

The third example is a more convenient alternative for the second case.

Warning

It is easy to abuse this feature, and it affects accessibility so use with care.

Internal document references

Use .. _label name: plus a blank line before any text location.

Then you can reference to those labels in the reST way (only works for labels within the document):

`label name`_

Example: citation

Or in the Sphinx way:

:ref:`displayed text <label>`

Which can be used between documents.

Example: paragraph

Alternatively, you can also use the :name: option in most blocks:

.. list-table::
   :header-rows: 0
   :name: list example

   ...

Example: list

Section titles, footnotes, and citations automatically are link targets.

Note

According to the Sphinx documentation you can also user the :ref: role directly with the label name (e.g. :ref:`label name`) if the label name is placed just before a section label.

Footnotes

You can create a footnote by:

Put the reference in the text [1]_.

.. [1] Footnote

Footnotes can have automatic labels with [#] 1.

1

In addition you can also use [#someText] that will be displayed as any other label.

Together with automatic labels there are also automatic symbols using [*].

Citations

With a similar syntax to footnotes, there are [citations]

.. [REL09] Citation

Is referenced as [REL09]_ REL09_ or rel09_.

citations

citation example

Other documents

Other documetns can be referenced with the :doc: directive.

:doc:`reference to a doc <includeDirective>`

reference to a doc

File includes

This text comes from a file that be included as from the current one with the include directive.

You can select only part of the file with the start-line and end-line options.

Check all the different options that you can use.

Example:

.. include:: includeDirective.rst

The literalinclude directive allows you to include the file into a container. This example:

.. literalinclude:: includeDirective.rst
   :language: text
   :linenos:

is shown as:

This text comes from a file
that be included as
from the current one
with the
``include`` directive.

You can select only part of the file with the *start-line* and *end-line* options.

Check all the different `options <http://docutils.sourceforge.net/docs/ref/rst/directives.html#include>`_ that you can use.

Python objects

See: cross-referencing Python. More information about it can be found in this document.