1.17. Referencing

Another important Sphinx feature is that it allows referencing across documents. This is another powerful way to tie documents together.

The simplest way to do this is to define an explicit reference object which can then be referenced directly as internal hyperlink target or with :ref:`refname` or in rare cases with :numref:`refname` depending on the toctree section numbering setup. Sphinx also supports :doc:`docname` for linking to a document via built-in extension sphinx.ext.intersphinx and also supports auto-generated labels for each section via built-in extension sphinx.ext.autosectionlabel.

The Hyperlink Targets in Docutils provides the basic specification for internal and external hyperlink targets. These are also called explicit and also available as implicit hyperlink targets.

:doc:
:ref:
:numref:

For more details, see doc, ref and numref role.

The example
1
2
3
4
5
6
Clicking on this internal hyperlink will take us to the target_ below.

:ref:`reference-name`, this is
:ref:`the same (cool) section <reference-name>`, and again the reference
with support of the extension **autosectionlabel** --
:ref:`concepts/referencing:A cool section` or :doc:`./referencing`.
1
2
3
4
5
6
7
8
.. _reference-name:

A cool section
""""""""""""""

.. _target:

The hyperlink target above points to this paragraph.
Which gives

Clicking on this internal hyperlink will take us to the target below.

A cool section, this is the same (cool) section, and again the reference with support of the extension autosectionlabelA cool section or Referencing.

1.17.1. A cool section

The hyperlink target above points to this paragraph.