Cross-Referencing Examples

General

In this example the reference consists of the following parts:

• The :py:mod:-role indicates that the target is a Python module. When the target however is addressed by a reference name, the :ref: role needs to be used. In this way one can cross-reference arbitrary locations. See: Cross-referencing syntax
• The role is followed by the reference enclosed in back-ticks (`). The reference consists of either:
  • just the reference-label for a local reference, e.g. local_intersphinx_label, or
  • the reference-label prefixed by the relevant key from the intersphinx_mapping dict, e.g. sphinx:xref-syntax
  • The reference can also be preceded by a link text and then enclosed in < and >.

One can use e.g. the following to search a site’s inventory file for the correct name:

$ python -msphinx.ext.intersphinx http://www.sphinx-doc.org/en/stable/objects.inv | grep -i intersphinx
sphinx.ext.intersphinx                   ext/intersphinx.html#module-sphinx.ext.intersphinx
sphinx-quickstart.--ext-intersphinx      man/sphinx-quickstart.html#cmdoption-sphinx-quickstart-ext-intersphinx
intersphinx_cache_limit                  ext/intersphinx.html#confval-intersphinx_cache_limit
intersphinx_mapping                      ext/intersphinx.html#confval-intersphinx_mapping
intersphinx_timeout                      ext/intersphinx.html#confval-intersphinx_timeout

Examples for local references:

• Local ref w/o link text: :ref:`local_intersphinx_label` becomes: Optional: Enable Inter-Sphinx
• Local ref with link text: :ref:`Local Intersphinx<local_intersphinx_label>` becomes: Local Intersphinx

Examples for Intersphinx references:

• Intersphinx ref w/o text: :ref:`sphinx:xref-syntax` becomes: Cross-referencing syntax
• Intersphinx ref with text: :ref:`X-Ref syntax<sphinx:xref-syntax>` becomes: X-Ref syntax
• Intersphinx mod w/o text: :mod:`python:math` becomes: math
• Intersphinx mod with text: :mod:`Python Math module<python:math>` becomes: Python Math module