I know how to create an external hyperlink with customized text.
`My cool link <http://www.asdf.com>`_
But I want to link to an internal reference.
.. _foo:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.
So I'd like to do something like
`My cool internal link <foo>`_
But this doesn't work.
When using reStructuredText with Sphinx, cross-reference other locations in the documentation with the ref role:
:ref:`link text <link-target>`
The custom link text is optional if the referenced object defines a title or caption, as is the case for documents, sections, figures, etc. The target's title will then be used as the link text, but the angle brackets must be left out: :ref:`link-target` . The link text is mandatory when referencing paragraphs or images, as they don't have titles/captions associated with them.
The link target has to be defined somewhere in the documentation, possibly in other documents, i.e. .rst files. For sections, the extension Autosectionlabel would do this automatically and the section's title then becomes the target, and thus also link text. In all other cases, internal hyperlink targets must be declared manually, for example like so:
.. _paragraph-to-be-linked-to:
This paragraph will be referenced from elsewhere in the documentation
with :ref:`that paragraph <paragraph-to-be-linked-to>`.
Note the leading underscore in the target definition. It can be thought of as a right-pointing arrow, here pointing inward, toward the link target. We may also link to specific positions inside (long) paragraphs with inline internal targets:
We want to point to _`this position` inside the paragraph
with :ref:`that paragraph <this position>` from elsewhere.
When using reStructuredText with Docutils alone, the ref role is not available, as it is a syntax extension added by Sphinx. Instead, we need the following syntax to create hyperlinks:
`link text <link-target_>`_
Note the two trailing underscores, one after the link target and another after the full hyperlink. Here the imaginary arrows point outward.
Docutils only processes standalone files. It is used by Sphinx as a back-end to parse individual reStructuredText source files. In Sphinx documentation, the latter syntax will therefore only work for internal links within the same document, but not across documents, i.e. a hyperlink defined in one .rst file referring to a target in another file.
Instead of the ref role, one may find the any role provided by Sphinx even more convenient. It will additionally find link targets automatically created by extensions, such as for source code objects documented with Autodoc. When declared as the default role in conf.py, with default_role = 'any', we could then write `link text <link-target>` or even just `link-target` to create internal hyperlinks. Except for the absence of trailing underscores, the former looks much like the syntax for single-document reStructuredText as recognized by Docutils, but is processed by Sphinx in a cross-document manner.