交叉引用

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

语法

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

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

  • 自定义链接文本： 您可以使用与 reStructuredText 外部链接 相同的符号显式指定链接文本：:role:`custom text <target>` 将引用 target 并将 custom text 显示为链接文本。

  • 抑制链接： 在前面加上感叹号 (!) 可防止创建链接，但会保留角色的视觉输出。

    例如，编写 :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: 角色将生成一个指向该章节的链接，链接标题为“要交叉引用的章节”。当章节和引用位于不同的源文件中时，这同样有效。

    自动标签也适用于图。例如

    .. _my-figure:

.. figure:: whatever

   Figure caption

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

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

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

注意

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

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

交叉引用文档

0.6 版本新增。

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

:doc:

链接到指定的文档；文档名称可以是相对路径或绝对路径，即使在 Windows 上也始终区分大小写。例如，如果引用 :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 文件中有一个全局词汇表。

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

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

交叉引用任何内容

: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 库的所有对象类型。