28.2. Referencing Components

Much of the documentation done by Sphinx involves referencing other components of the documentation. For example, when writing the command :py:func:`examplemodule.dummy_function_example`, you are referencing a documented Python function of this name. Sphinx then automatically creates a reference link to this function for you, displayed as examplemodule.dummy_function_example(). You can also create your own references to most other components of the documentation, such as sections, code-blocks, and figures. To create a custom reference you should put the reference directive just prior to the component you want to reference. For example, in order to create a reference to this section this code was used

.. _referencing_things:

Referencing Components
----------------------

Important

Notice that the reference name _referencing_things has a leading underscore. This is not part of the name. When using the reference you omit this underscore.

We can then make a reference to this section by using :ref:`referencing_things` which displays as Referencing Components. If you prefer to have a numbered reference, we could instead use :numref:`referencing_things` which displays as Section 28.2.

We also have enabled a extension to automatically define references for all sections. So without adding anything this section could also be referenced by :ref:`framework/doc/referencing:Referencing Components` which still result in Referencing Components.