交叉引用语法

交叉引用是由许多语义解释的文本角色生成的。基本上，您只需编写“:role:`target`”，并且将创建一个指向*target*的项目的链接，该项目的类型由*role*表示。链接的文本将与*target*相同。

但是，还有一些附加功能使交叉引用角色更加通用：

• 您可以提供一个显式的标题和引用目标，如在reST直接超链接中：“:role:`title <target>`”将引用*target*，但链接文本将是*title*。

• 如果在内容前加上“！” ，则不会创建引用或超链接。

• 如果在内容前面加上“~”，则链接文本将仅是目标的最后一个组件。例如，“get()”将指“Queue.Queue.get”但只显示“get”作为链接文本。这并不适用于所有交叉引用角色，而是特定于域的。

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

交叉引用任何内容

:any:

Added in version 1.3.

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

• 首先，它尝试标准的交叉引用目标，这些目标将被以下对象引用 doc，ref 或 option。

  通过扩展添加到标准域的自定义对象（请参见： Sphinx.add_object_type())也会被搜索。

• 然后，它在所有加载的域中查找对象（目标）。匹配的具体程度取决于域。例如，在Python域中，“Builder”的引用将匹配“sphinx.builders.Builder”班级。

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

This role is a good candidate for setting default_role. If you do, you can write cross-references without a lot of markup overhead. For example, in this Python function documentation:

.. function:: install()

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

可能有对术语表术语（通常是“handler”）、Python模块（通常为“signal”或“signal”）和一个部分（通常为“about-signals”）。

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

交互参考对象

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

• Python

• C

• C++

• JavaScript

• ReST

交叉引用任意位置

: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
  

  在这种情况下，引用“my-figure”会插入一个引用到图，链接文本为“figure caption”。

  对于使用：dudir:`table`指令给出显式标题的表，同样的方法也适用。

• 没有放在节标题之前的标签仍然可以被引用，但是必须给链接一个显式的标题，使用以下语法：“Link title”。

备注

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

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

交叉引用文件

Added in version 0.6.

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

:doc:

链接到指定的文档；可以以绝对或相对方式指定文档名称。例如，如果引用“:doc:`parrot”出现在文档“sketches/index`”中，那么该链接引用的是“sketces/parrot`”。如果引用是“/people”或“` or ``../people”，那么链接就是“people”。

如果没有给出明确的链接文本（像通常的：“Monty Python members”），那么链接标题将是给定文档的标题。

引用可下载文件

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 role can also refer sections. And numref allows {name} for the link text.

:numref:

链接到指定的图、表、代码块和节；使用标准reST标签。当您使用这个角色时，它将插入一个引用，通过图号（如“图1.1”）链接文本。

如果给出一个明确的链接文本（通常为：“Image of Sphinx（图%s）1”），则链接标题将作为引用的标题。作为占位符，`%s`和{number}`将被图号替换，而{name}`将被图标题替换。如果没有给出明确的链接文本，则：confval:`numfig_format`设置将用作回退默认值。

如果：confval:`numfig`是“False”，则数字没有编号，因此此角色插入的不是引用而是标签或链接文本。

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

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

:envvar:

环境变量。生成索引项，同时生成指向匹配项的链接:rst:dir:`envvar`指令（如果存在）。

:token:

语法标记的名称（用于在以下对象之间创建链接 productionlist 指令）。

:keyword:

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

:option:

可执行程序的命令行选项。这将生成一个链接 option 指令（如果存在）。

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

:term:

对术语表中术语的引用。术语表是使用“glossary”指令创建的，该指令包含一个包含术语和定义的定义列表。它不必与“term”标记在同一个文件中，例如Python文档在“词汇表.rst”文件。

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