交叉引用语法¶

交叉引用是由许多语义解释文本角色生成的。基本上，你只需要写 :role:`target `将创建一个指向名为目标所示类型的 role . 链接的文本将与目标 .

但是，还有一些附加的工具使交叉引用角色更加通用：

您可以提供明确的标题和引用目标，如REST直接超链接： :role:`title <target> “将指目标，但链接文本将标题 .
如果在内容前面加上前缀 ! ，不会创建引用/超链接。
如果在内容前面加上前缀 ~ ，链接文本将仅是目标的最后一个组件。例如， :py:meth:`~Queue.Queue.get “将指 Queue.Queue.get 但只显示 get 作为链接文本。这不适用于所有交叉引用角色，但特定于域。

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

交叉引用任何内容¶

:any:¶

Added in version 1.3.

这个便利角色尽力为其引用文本找到一个有效的目标。

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

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

如果未找到任何目标或多个目标，将发出警告。对于多个目标，可以将“任意”更改为特定角色。

这个角色很适合设置 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模块（通常 `signal` 或 :mod:`signal ）和一个部分（通常 `about-signals` ''。

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

交叉引用对象¶

这些角色用各自的领域来描述：

交叉引用任意位置¶

:ref:¶

为了支持对任何文档中任意位置的交叉引用，使用标准的REST标签。为此，在整个文档中，工作标签名称必须是唯一的。有两种方法可以引用标签：

如果将标签直接放置在节标题之前，可以使用 :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 `将插入对带有链接文本“图形标题”的图形的引用。

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

备注

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

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

交叉引用文档¶

Added in version 0.6.

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

:doc:¶

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

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

引用可下载文件¶

Added in version 0.6.

:download:¶

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

当您使用此角色时，被引用的文件将在生成时自动标记为包含在输出中（显然，仅用于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:¶

链接到指定的图形、表格、代码块和节；使用标准的REST标签。当您使用此角色时，它将通过其图号（如“图1.1”）插入对带有链接文本的图的引用。

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

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

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

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

:envvar:¶: 环境变量。生成索引项。同时生成到匹配的链接 envvar 指令（如果存在）。

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

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

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

以下角色创建对 glossary ：

:term:¶

指术语表中的术语。使用创建词汇表 glossary 包含带有术语和定义的定义列表的指令。它不必与 term 标记，例如，python文档在 glossary.rst 文件。

如果使用词汇表中没有解释的术语，则在构建期间会收到警告。

Sphinx

On this page

Site navigation