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
andnumref
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 autosectionlabel – A cool section or Referencing.
1.17.1. A cool section¶
The hyperlink target above points to this paragraph.