交叉引用

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:

链接到指定的文档；文档名称可以以绝对或相对方式指定。 例如，如果引用 :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 清单的所有对象类型。