交叉引用语法¶

交叉引用是由许多语义解释的文本角色生成的.基本上,您只需要写``:role:target``, 就会创建一个指向类型为 role 的名为 target 的项的链接. 链接的文本将与 target 相同.

然而,还有一些额外的功能,使得交叉引用的角色更加灵活:

您可以提供一个明确的标题和引用目标,就像在reStructuredText直接超链接中一样:``:role:`title <target>```将会引用*target*,但链接文本将是*title*.
如果您在内容前加上 ! ,则不会创建引用/超链接.
如果您在内容前加上 ~ ,链接文本将仅为目标的最后一个组件.例如,``: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` 类.

如果未找到目标或找到多个目标,将会发出警告. 在多个目标的情况下,您可以将 “any” 更改为特定角色.

此角色是设置 :confval :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``）.

The any role also works together with the intersphinx extension: when no local cross-reference is found, all object types of intersphinx inventories are also searched.

交叉引用对象¶

这些角色及其相应的领域如下:

交叉引用任意位置¶

: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`.
```
The :ref: role would then generate a link to the section, with the link title being “Section to cross-reference”. This works just as well when section and reference are in different source files.

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

.. figure:: whatever

   Figure caption
```
在这种情况下,引用``:ref:`my-figure```将插入一个指向图形的引用,链接文本为 “图形标题”.

使用 table 指令显式给出的表格同样适用.
在节标题之前没有放置的标签仍然可以被引用,但您必须给链接一个明确的标题,使用以下语法::ref:`链接标题 <标签名称> .

备注

引用标签必须以下划线开头.引用标签时,必须省略下划线（见上面的例子）.

使用 ref 比标准的 reStructuredText 链接到部分 (比如```Section title`_``) 更被推荐,因为它可跨文件工作,在章节标题更改时会发出警告,如果不正确,它会提示错误,并且对所有支持交叉引用的构建器都有效.

跨文档引用¶

Added in version 0.6.

还可以直接链接到文档:

:doc:¶

链接到指定文档;文档名称可以绝对或相对指定.例如,如果在文档 sketches/index 中出现引用``:doc:parrot`` ,则链接指向 sketches/parrot .如果引用是``:doc:/people```或`../people ` ,则链接指向`` people`` .

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

引用可下载文件¶

Added in version 0.6.

:download:¶

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

当你使用这个角色时,引用的文件在构建时会自动标记为包含在输出中（显然,仅限 HTML 输出）.所有可下载的文件都被放入输出目录的 _downloads/<唯一哈希>/ 子目录中;重复的文件名会被处理.

一个示例:

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

给定的文件名通常相对于当前源文件所在的目录,但如果是绝对路径（以 / 开头）,则相对于顶级源目录.

The example.py file will be copied to the output directory, and a suitable link generated to it.

不显示不可用的下载链接,您应该将具有此角色的整段文本包裹起来:

.. only:: builder_html

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

按图号交叉引用图形¶

Added in version 1.3.

在 1.5 版本发生变更: numref 角色也可以引用章节.而 numref 允许使用 {name} 作为链接文本.

:numref:¶

链接到指定的图形、表格、代码块和章节;使用标准的reStructuredText标签.当您使用此角色时,它将插入一个对图形的引用,链接文本为图形编号,例如 “图 1.1”.

如果提供了明确的链接文本（通常为::numref:`Image of Sphinx (Fig. %s) <my-figure>`）,则链接标题将作为引用的标题.占位符 %s 和 {number} 将被图形编号替换, {name} 将被图形标题替换.如果没有提供明确的链接文本,则使用 numfig_format 设置作为备选默认值.

如果 numfig 为 False ,则图形不被编号,因此该角色插入的不是引用,而是标签或链接文本.

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

以下角色可能创建交叉引用,但不引用对象:

:confval:¶: 一个配置值或设置.索引条目已生成.如果存在,还会生成指向匹配的 confval 指令的链接.

:envvar:¶: 一个环境变量.生成索引条目.如果存在,还会生成指向匹配的 envvar 指令的链接.

:token:¶: 一个语法符号的名称（用于在:rst:dir:productionlist 指令之间创建链接）.

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

:option:¶: 可执行程序的命令行选项.如果存在,此选项会生成指向 option 指令的链接.

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

:term:¶

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

如果您使用的术语未在术语表中解释,构建时将收到警告.