交叉引用语法¶
交叉引用是由许多语义解释文本角色生成的。基本上,你只需要写 :role:`target
`将创建一个指向名为 目标 所示类型的 role . 链接的文本将与 目标 .
但是,还有一些附加的工具使交叉引用角色更加通用:
您可以提供明确的标题和引用目标,如REST直接超链接:
:role:`title <target>
“将指 目标 ,但链接文本将 标题 .如果在内容前面加上前缀
!
,不会创建引用/超链接。如果在内容前面加上前缀
~
,链接文本将仅是目标的最后一个组件。例如,:py:meth:`~Queue.Queue.get
“将指Queue.Queue.get
但只显示get
作为链接文本。这不适用于所有交叉引用角色,但特定于域。在HTML输出中,链接的
title
属性(如鼠标悬停时显示为工具提示)始终是完整的目标名称。
交叉引用任何内容¶
- :any:¶
Added in version 1.3.
这个便利角色尽力为其引用文本找到一个有效的目标。
首先,它尝试将被引用的标准交叉引用目标
doc
,ref
或option
.通过扩展添加到标准域的自定义对象(请参见
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.
还有一种直接链接到文档的方法:
引用可下载文件¶
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.
- :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, thenumfig_format
setting is used as fall-back default.如果
numfig
是False
,图形没有编号,因此此角色插入的不是引用,而是标签或链接文本。
交叉引用其他感兴趣的项目¶
以下角色可能会创建交叉引用,但不引用对象:
- :token:¶
语法标记的名称(用于在
productionlist
指令)。
- :keyword:¶
python中关键字的名称。这将创建指向具有该名称的引用标签(如果存在)的链接。
以下角色创建对 glossary :
- :term:¶
指术语表中的术语。使用创建词汇表
glossary
包含带有术语和定义的定义列表的指令。它不必与term
标记,例如,python文档在glossary.rst
文件。如果使用词汇表中没有解释的术语,则在构建期间会收到警告。