使用 reStructuredText 与
Sphinx 一起,可以使用
ref
role 引用文档中的其他位置:
: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.
使用单独的
Docutils时,reStructuredText中没有
ref
角色,因为它是由Sphinx添加的语法扩展。相反,我们需要以下语法来创建
超链接:
`link text <link-target_>`_
请注意两个下划线,一个在链接目标后面,另一个在完整超链接之后。这里的想象箭头指向外部。
Docutils仅处理独立文件。它被Sphinx用作解析单个reStructuredText源文件的后端。在Sphinx文档中,后一种语法仅适用于同一文档内的内部链接,而不适用于跨文档,即在一个.rst文件中定义的超链接引用到另一个文件中的目标。
与ref
角色不同,人们可能会发现Sphinx提供的any
角色更方便。它还将自动查找由扩展创建的链接目标,例如使用Autodoc记录的源代码对象。当在conf.py
中声明为默认角色时,使用default_role = 'any'
,我们可以编写`链接文本<链接目标>`
甚至只需`链接目标`
即可创建内部超链接。除了没有下划线之外,前者看起来很像Docutils识别的单文档reStructuredText语法,但是由Sphinx以跨文档方式处理。