交叉引用语法

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

但是，还有一些其他功能使交叉引用角色更加通用。

• 您可以像在 reStructuredText 直接超链接中一样提供显式标题和引用目标：:role:`title` <target>` 将引用 target，但链接文本将是 title。

• 如果在内容前加上 !，则不会创建引用/超链接。

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

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

交叉引用任何内容

: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`）和章节（通常为 :ref:`about-signals`）的引用。

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

交叉引用对象

这些角色及其各自的域一起描述

• Python

• C

• C++

• JavaScript

• reStructuredText

交叉引用任意位置

: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` 将插入对图形的引用，链接文本为“图形标题”。

  这同样适用于使用 table 指令给出显式标题的表格。

• 未放在节标题之前的标签仍然可以引用，但您必须为链接提供显式标题，使用以下语法：:ref:`Link title <label-name>`。

注意

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

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

交叉引用文档

版本 0.6 中新增。

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

:doc:

链接到指定的文档；文档名称可以以绝对或相对方式指定。例如，如果引用 :doc:`parrot` 出现在文档 sketches/index 中，则该链接指向 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:

链接到指定的图形、表格、代码块和节；使用标准的 reStructuredText 标签。当您使用此角色时，它将插入对图形的引用，链接文本为其图号，例如“图 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 指令的链接。

以下角色创建到 词汇表 中术语的交叉引用

:term:

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

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

上一页

Markdown

下一页

配置