交叉引用¶

Sphinx最有用的功能之一是通过语义交叉引用角色创建自动交叉引用。对对象描述的交叉引用，例如 :func:`spam '，将创建一个链接到 spam() 已记录在案，适合每种输出格式（HTML、PDF、ePUB等）。

语法¶

Sphinx支持各种交叉引用角色来创建指向文档中其他元素的链接。总的来说，写作 :role:`target '创建一个指向名为 target 属于由以下指示的类型 role .链接的文本取决于角色，但通常与 target .

可以通过以下方式修改该行为：

Custom link text: 您可以使用与reStructuredtext中相同的符号显式指定链接文本 external links : :role:`custom text <target> '将指的是 target 和显示 custom text 作为链接的文本。
Suppressed link: 前面有感叹号 (! ）阻止创建链接，但否则会保留角色的视觉输出。

例如，写作 :py:func:`!target '显示 target() ，没有生成任何链接。

这对于链接目标不存在的情况很有帮助;例如，描述已删除功能的更改日志条目，或不支持的第三方库 intersphinx .抑制链接可防止 nitpicky 模式
Modified domain reference: 当 referencing domain objects ，波浪形 ~ 前置将链接文本缩短到目标的最后一个组件。例如， :py:meth:`~queue.Queue.get '将指的是 queue.Queue.get 只显示 get 作为链接文本。

在HTML输出中，链接的 title 属性（例如，在鼠标悬停时显示为工具提示）将始终是完整的目标名称。

交叉引用对象¶

这些角色通过各自的领域进行了描述：

交叉引用任意位置¶

:ref:¶

为了支持交叉引用任何文档中的任意位置，请使用标准的reStructuredtext标签。为此，标签名称在整个文档中必须是唯一的。您可以通过两种方式引用标签：

如果将标签直接放在部分标题之前，则可以使用以下方式引用它 :ref:`label-name `. 例如：：
```
.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.
```
的 :ref: 然后，角色将生成该部分的链接，链接标题为“交叉引用的部分”。当小节和引用位于不同的源文件中时，这也很有效。

自动标签也适用于图形。例如：：
```
.. _my-figure:

.. figure:: whatever

   Figure caption
```
在这种情况下，参考 :ref:`my-figure '将插入对带有链接文本“Figure title”的图形的引用。

对于使用 table 指令。
未放置在部分标题之前的标签仍然可以引用，但您必须使用以下语法为链接指定显式标题： :ref:`Link title <label-name> `.

备注

参考标签必须以强调线开头。引用标签时，必须省略下划线（请参阅上面的示例）。

使用 ref 建议通过标准的reStructured文本链接到部分（例如 `Section title`_ ），因为它跨文件工作，当部分标题更改时，如果不正确，会发出警告，并且适用于所有支持交叉引用的构建器。

交叉引用文档¶

Added in version 0.6.

还有一种方法可以直接链接到文档：

:doc:¶

链接到指定的文档;文档名称可以以绝对或相对的方式指定。例如，如果引用 :doc:`parrot '发生在文档中 sketches/index ，那么链接指的是 sketches/parrot . 如果参考是 :doc:`/people 或 `../people` '，链接指的是 people .

如果没有给出明确的链接文本（像往常一样： :doc:`Monty Python members </people> '），链接标题将是给定文档的标题。

引用可下载文件¶

Added in version 0.6.

:download:¶

此角色允许您链接到源树中的文件，这些文件不是可以查看的reStructuredText文档，而是可以下载的文件。

当您使用此角色时，引用的文件会自动标记为包含在构建时的输出中（显然，仅适用于HTML输出）。所有可下载的文件都被放入 _downloads/<unique hash>/ 输出目录的格式;重复的文件名被处理。

例如：

See :download:`this example script <../example.py>`.

给定的文件名通常相对于当前源文件所在的目录，但如果它是绝对的（以 / ），它被视为相对于顶级源目录。

的 example.py 文件将被复制到输出目录，并生成合适的链接。

为了不显示不可用的下载链接，您应该包装具有此角色的整个段落：：

.. only:: builder_html

   See :download:`this example script <../example.py>`.

按图号相互参照图¶

Added in version 1.3.

在 1.5 版本发生变更: numref 角色也可以引用部分。和 numref 允许 {name} 对于链接文本。

:numref:¶

链接到指定的图形、表格、代码块和部分;使用标准的reStructuredtext标签。当您使用此角色时，它将通过图形编号插入对带有链接文本的图形的引用，例如“Fig.1.1”。

如果给出了显式链接文本（照常： :numref:`Image of Sphinx (Fig. %s) <my-figure> '），链接标题将作为参考文献的标题。作为占位者， %s 和 {number} 被数字取代， {name} 按图标题。如果没有给出显式链接文本， numfig_format 设置用作后备默认设置。

如果 numfig 是 False ，图形没有编号，因此此角色插入的不是引用，而是标签或链接文本。

交叉引用其他感兴趣的项目¶

以下角色可能会创建交叉引用，但不会引用对象：

:confval:¶: 配置值或设置。生成索引条目。还生成匹配的链接 confval 指令（如果存在的话）。

:envvar:¶: 环境变量。生成索引条目。还生成匹配的链接 envvar 指令（如果存在的话）。

:token:¶: 语法标记的名称（用于在 productionlist 指令）。

:keyword:¶: Python中关键字的名称。这将创建指向具有该名称的参考标签（如果存在）的链接。

:option:¶: 可执行程序的命令行选项。这会生成指向 option 指令（如果存在的话）。

以下角色创建对中术语的交叉引用 glossary :

:term:¶

对术语表中术语的引用。使用创建术语表 glossary 包含包含术语和定义的定义列表的指令。它不必与 term 标记，例如Python文档中有一个全局术语表 glossary.rst 文件.

如果您使用术语表中未解释的术语，您将在构建期间收到警告。

这个角色还支持 custom link text 来自一般交叉引用语法。

交叉引用任何内容¶

:any:¶

Added in version 1.3.

这个方便角色试图尽最大努力为其参考文本找到有效目标。

首先，它尝试将被引用的标准交叉引用目标 doc , ref 或 option .

通过扩展添加到标准域的自定义对象（请参阅 Sphinx.add_object_type() ）也被搜索。
然后，它在所有加载的域中寻找对象（目标）。匹配的具体程度取决于域。例如，在Python领域中引用 :any:`Builder ”将匹配的。 sphinx.builders.Builder 课

如果没有发现或发现多个目标，将发出警告。如果有多个目标，您可以将“any”更改为特定角色。

这个角色是一个很好的人选 default_role . 如果您这样做，您就可以编写交叉引用，而无需花费大量的标记费用。例如，在此Python函数文档中：：

.. function:: install()

   This function installs a `handler` for every signal known by the
   `signal` module.  See the section `about-signals` for more information.

可能会引用术语表术语（通常 :term:`handler '），Python模块（通常 :py:mod:`signal 或 `signal` ）和一个部分（通常 :ref:`about-signals `）.

的 any 该角色还与 intersphinx 扩展：当没有找到本地交叉引用时，也会搜索interphinx清单的所有对象类型。