交叉引用语法

交叉引用是由许多语义解释文本角色生成的。基本上,你只需要写 :role:`target `将创建一个指向名为 目标 所示类型的 role . 链接的文本将与 目标 .

但是,还有一些附加的工具使交叉引用角色更加通用:

  • 您可以提供明确的标题和引用目标,如REST直接超链接: :role:`title <target> “将指 目标 ,但链接文本将 标题 .

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

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

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

交叉引用任何内容

:any:

Added in version 1.3.

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

  • 首先,它尝试将被引用的标准交叉引用目标 docrefoption .

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

  • 然后,它在所有加载的域中查找对象(目标)。匹配的具体程度取决于域。例如,在python域中, :any:`Builder 将匹配 ``sphinx.builders.Builder` 班级。

如果未找到任何目标或多个目标,将发出警告。对于多个目标,可以将“任意”更改为特定角色。

这个角色很适合设置 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模块(通常 `signal`:mod:`signal )和一个部分(通常 `about-signals` ''。

这个 any 角色还与 intersphinx 扩展:当没有找到本地交叉引用时,也会搜索所有的interphinx库存对象类型。

交叉引用对象

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

交叉引用任意位置

: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
    

    在这种情况下,参考 :ref:`my-figure `将插入对带有链接文本“图形标题”的图形的引用。

    对于使用 table 指令。

  • 仍可以引用节标题之前未放置的标签,但必须使用以下语法为链接指定明确的标题: :ref:`Link title <label-name> '.

备注

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

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

交叉引用文档

Added in version 0.6.

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

:doc:

链接到指定的文档;可以绝对或相对方式指定文档名。例如,如果引用 :doc:`parrot 在文档中发生 ``sketches/index` ,则链接引用 sketches/parrot . 如果参考是 :doc:`/people:doc:`../people 链接引用 ``people` .

如果没有给出明确的链接文本(与通常一样: :doc:`Monty Python members </people> `链接标题将是给定文档的标题。

引用可下载文件

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 角色也可以参考章节。和 numref 允许 {name} 用于链接文本。

:numref:

链接到指定的图形、表格、代码块和节;使用标准的REST标签。当您使用此角色时,它将通过其图号(如“图1.1”)插入对带有链接文本的图的引用。

If an explicit link text is given (as usual: :numref:`Image of Sphinx (Fig. %s) <my-figure>`), the link caption will serve as title of the reference. As placeholders, %s and {number} get replaced by the figure number and {name} by the figure caption. If no explicit link text is given, the numfig_format setting is used as fall-back default.

如果 numfigFalse ,图形没有编号,因此此角色插入的不是引用,而是标签或链接文本。

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

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

:envvar:

环境变量。生成索引项。同时生成到匹配的链接 envvar 指令(如果存在)。

:token:

语法标记的名称(用于在 productionlist 指令)。

:keyword:

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

:option:

可执行程序的命令行选项。这将生成指向 option 指令(如果存在)。

以下角色创建对 glossary

:term:

指术语表中的术语。使用创建词汇表 glossary 包含带有术语和定义的定义列表的指令。它不必与 term 标记,例如,python文档在 glossary.rst 文件。

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