重构文本中的内部超链接,带有自定义文本

Question

我知道如何使用自定义文本创建外部超链接.

`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>`_

但这不起作用.

Answer 1

解:

`My cool internal link <foo_>`_

Answer 2

在文本上使用2个下划线,在链接目标上使用1个不需要的核心,例如:

`My cool internal link <foo_>`__

... somewhere lower ...

.. _foo:

This staff is referenced by "My cool internal link"

当我使用一个下划线而不是2时,rst2pdf会抛出错误.

Answer 3

将 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.

当 reStructuredText 单独与Docutils一起使用时，该ref角色不可用，因为它是 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`