交叉引用¶

Sphinx最有用的功能之一是通过语义交叉引用角色来创建自动交叉引用。对对象描述（比如 :func:`spam`）的交叉引用将创建一个链接，指向 spam() 文档记录的位置，适用于每种输出格式（HTML、PDF、ePUB等）。

语法¶

Sphinx支持各种交叉引用角色，以创建指向文档中其他元素的链接。通常，编写 :role:`target` 会创建一个指向 role 指示的类型的 target 对象的链接。链接的文本取决于角色，但通常与 target 相同或相似。

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

自定义链接文本： 您可以使用与reStructuredText 外部链接中相同的符号明确指定链接文本： :role:`自定义文本 <target>` 将引用 target 并显示 自定义文本 作为链接文本。
抑制链接： 以感叹号（!）为前缀可防止创建链接，但在其他方面保留该角色的视觉输出。

例如，编写 :py:func:`!target` 显示 target()，但不会生成链接。

这对于链接目标不存在的情况很有帮助；例如，描述已删除功能的变更日志条目，或不支持 intersphinx 的第三方库。抑制链接可防止在 nitpicky 模式下发出警告。
修改域引用:当交叉引用其它语言域的对象时，波浪号~前缀将链接文本缩短为目标的最后一个组件。例如，: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: 角色所在处将生成一个到节的链接，显示的链接文本为"Section to cross-reference"（即label下方的章节的名字）。当节和引用位于不同的源文件中时，这种方法同样有效。

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

.. figure:: whatever

   Figure caption
```
在这种情况下，引用 :ref:`my-figure` 会插入一个引用到图，链接文本为 "Figure caption"。

对于使用 table 指令给出显式标题的表，同样的方法也适用。
没有放在节标题之前的标签仍然可以被引用，但是必须给链接一个显式的标题，使用以下语法：:ref:`Link title <label-name>`。

备注

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

使用 ref 比标准的reStructuredText链接到节(如 `Section title`_ )更可取，因为它可以跨文件工作，当节标题更改时，如果不正确将发出警告，并且适用于所有支持交叉引用的构建器。

交叉引用文件¶

在 0.6 版本加入.

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

:doc:¶

链接到指定的文档；文档名称可以是相对路径或绝对路径，并且始终区分大小写，即使在Windows上也是如此。例如，如果在文档 sketches/index 中出现引用 :doc:`parrot`，则链接引用 sketches/parrot。如果引用是 :doc:`/people` 或 :doc:`../people`，则链接引用 people。

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

引用可下载文件¶

在 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>`.

图号对照图¶

在 1.3 版本加入.

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

:numref:¶

链接到指定的图、表、代码块和节(section)；使用标准的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文件中有一个全局的术语表。

如果您使用一个没在术语表中定义的术语，您将在构建期间收到警告。

这个角色还支持来自通用交叉引用语法的自定义链接文本。

交叉引用任何内容¶

:any:¶

在 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` 或 :mod:`signal`)和一个section(通常为 :ref:`about-signals`)的引用。

any角色也能与intersphinx扩展一起工作：当没有找到本地交叉引用时，还会搜索intersphinx库存的所有对象类型。