我知道如何使用自定义文本创建外部超链接。
`My cool link <http://www.asdf.com>`_
但我想链接到内部参考。
.. _foo:
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
eiusmod tempor incididunt ut labore et dolore magna aliqua.
所以我想做类似的事情
`My cool internal link <foo>`_
但这不起作用。
解决方案：
`My cool internal link <foo_>`_
在文本上使用 2 个下划线，在链接目标上使用 1 个取消划线，例如：
`My cool internal link <foo_>`__
... somewhere lower ...
.. _foo:
This staff is referenced by "My cool internal link"
当我使用一个下划线而不是 2 时，rst2pdf 会引发错误。
如果约翰的解决方案不适合您：
`My cool internal link<foo>`
将 reStructuredText 与Sphinx一起使用时，请使用角色交叉引用文档中的其他位置ref：
:ref:`link text <link-target>`
如果引用的对象定义了标题或标题，则自定义链接文本是可选的，例如文档、部分、图形等。目标的标题将用作链接文本，但必须省略尖括号：:ref:`link-target` . 引用段落或图像时，链接文本是强制性的，因为它们没有与之关联的标题/说明。
链接目标必须在文档中的某处定义，可能在其他文档中，即文件.rst中。对于部分，扩展Autosectionlabel会自动执行此操作，然后部分的标题成为目标，因此也链接文本。在所有其他情况下，必须手动声明内部超链接目标，例如：
.. _paragraph-to-be-linked-to:
This paragraph will be referenced from elsewhere in the documentation
with :ref:`that paragraph <paragraph-to-be-linked-to>`.
注意目标定义中的前导下划线。它可以被认为是一个向右的箭头，这里指向内部，指向链接目标。我们还可以使用内联内部目标链接到（长）段落中的特定位置：
We want to point to _`this position` inside the paragraph
with :ref:`that paragraph <this position>` from elsewhere.
单独使用带有Docutilsref的 reStructuredText 时，该角色不可用，因为它是 Sphinx 添加的语法扩展。相反，我们需要以下语法来创建超链接：
`link text <link-target_>`_
注意两个尾随下划线，一个在链接目标之后，另一个在完整超链接之后。这里假想的箭头指向外面。
Docutils 只处理独立文件。Sphinx 使用它作为后端来解析单个 reStructuredText 源文件。因此，在 Sphinx 文档中，后一种语法仅适用于同一文档中的内部链接，但不适用于跨文档，即在一个.rst文件中定义的超链接引用另一个文件中的目标。
代替ref角色，可能会发现Sphinx 提供的any角色更方便。它还将查找由扩展自动创建的链接目标，例如使用Autodoc记录的源代码对象。当在, with中声明为默认角色时，我们可以编写甚至只是创建内部超链接。除了没有尾随下划线之外，前者看起来很像 Docutils 识别的单文档 reStructuredText 的语法，但由 Sphinx 以跨文档方式处理。conf.pydefault_role = 'any'`link text <link-target>``link-target`
您只需要删除自定义标题之后和尖括号之前的空格，然后使用:ref:指令：
这有效：
:ref:`My cool internal link with no space before bracket<foo>`
这不会：
:ref:`My cool internal link with space <foo>`