角色

Sphinx 使用解释性文本角色在文档中插入语义标记。它们的书写格式为 :rolename:`content`。

注意

默认角色 (`content`) 默认情况下没有特殊含义。您可以随意将其用于任何目的，例如变量名；使用 default_role 配置值将其设置为已知角色 — any 角色用于查找任何内容，或 py:obj 角色用于查找 Python 对象，这些都非常有用。

有关域添加的角色，请参见域。

交叉引用

请参阅交叉引用。

交叉引用角色包括

内联代码高亮

:code:

一个内联代码示例。当直接使用时，此角色仅显示文本，不进行语法高亮，作为一个字面量。

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

显示：默认情况下，内联代码，如 1 + 2，仅显示，不进行高亮。

与 code-block 指令不同，此角色不遵循 highlight 指令设置的默认语言。

要启用语法高亮，您必须首先使用 Docutils 的 role 指令来定义与特定语言关联的自定义角色

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

要显示多行代码示例，请改用 code-block 指令。

数学

:math:

内联数学公式的角色。使用方法如下

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

显示：根据勾股定理，我们知道 \(a^2 + b^2 = c^2\)。

:eq:

与 math:numref 相同。

其他语义标记

以下角色除了以不同样式格式化文本外，不执行任何特殊操作

:abbr:

一个缩写词。如果角色内容包含括号中的解释，它将被特殊处理：在 HTML 中会显示为工具提示，在 LaTeX 中只输出一次。

例如：:abbr:`LIFO (last-in, first-out)` 显示 LIFO。

0.6 版本新增。

:command:

OS 级别命令的名称，例如 rm。

例如：rm

:dfn:

标记文本中术语的定义实例。（不生成索引条目。）

例如：二进制模式

:file:

文件或目录的名称。在内容中，您可以使用大括号来表示“变量”部分，例如

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

显示：… 安装在 /usr/lib/python3.x/site-packages … 中

在生成的文档中，x 将以不同方式显示，表示它将被替换为 Python 小版本。

:guilabel:

作为交互式用户界面一部分呈现的标签应使用 guilabel 标记。这包括来自基于文本的界面的标签，例如使用 curses 或其他基于文本的库创建的标签。界面中使用的任何标签都应使用此角色标记，包括按钮标签、窗口标题、字段名称、菜单和菜单选择名称，甚至选择列表中的值。

版本 1.0 中有改动: GUI 标签的加速键可以使用 & 符号包含；这将从输出中删除并以下划线显示（例如：:guilabel:`&Cancel` 显示 Cancel）。要包含字面 & 符号，请将其加倍。

:kbd:

标记一个按键序列。按键序列的形式可能取决于平台或应用程序的特定约定。当没有相关约定时，修饰键的名称应拼写出来，以提高新用户和非母语使用者的可访问性。例如，一个 xemacs 按键序列可以标记为 :kbd:`C-x C-f`，但如果未引用特定应用程序或平台，则相同的序列应标记为 :kbd:`Control-x Control-f`，分别显示 C-x C-f 和 Control-x Control-f。

:mailheader:

RFC 822 样式邮件头部的名称。此标记并不意味着头部正在电子邮件消息中使用，但可用于引用任何相同“样式”的头部。这也用于各种 MIME 规范定义的头部。头部名称应以通常在实践中找到的方式输入，如果存在多种常见用法，则首选驼峰命名约定。例如：:mailheader:`Content-Type` 显示 Content-Type。

:makevar:

make 变量的名称。

例如：help

:manpage:

对 Unix 手册页的引用，包括章节，例如 :manpage:`ls(1)` 显示 ls(1)。如果定义了 manpages_url，则会创建指向渲染手册页的外部站点的超链接。

版本 7.3 中有改动: 允许使用 <> 指定目标，就像超链接一样。例如，:manpage:`blah <ls(1)>` 显示 blah。

:menuselection:

菜单选择应使用 menuselection 角色标记。这用于标记完整的菜单选择序列，包括选择子菜单和选择特定操作，或此类序列的任何子序列。各个选择的名称应由 --> 分隔。

例如，要标记选择“开始 > 程序”，请使用此标记

:menuselection:`Start --> Programs`

显示：开始 ‣ 程序

当包含包含某些尾随指示符的选择时，例如某些操作系统用来指示命令打开对话框的省略号，指示符应从选择名称中省略。

menuselection 也支持像 guilabel 一样的 & 符号加速器。

:mimetype:

MIME 类型的名称，或 MIME 类型的一个组件（主要或次要部分，单独取）。

例如：text/plain

:newsgroup:

Usenet 新闻组的名称。

例如：comp.lang.python

:program:

可执行程序的名称。这可能与某些平台上的可执行文件名不同。特别是，Windows 程序应省略 .exe（或其他）扩展名。

例如：curl

:regexp:

正则表达式。不应包含引号。

例如：([abc])+

:samp:

一段字面文本，例如代码。在内容中，您可以使用花括号来表示“变量”部分，如 file 中所示。例如，在 :samp:`print(1+{variable})` 中，variable 部分将被强调：print(1+variable)

如果您不需要“变量部分”指示，请改用标准的 code 角色。

版本 1.8 中有改动: 允许用双反斜杠转义花括号。例如，在 :samp:`print(f"answer=\\{1+{variable}*2\\}")` 中，variable 部分将被强调，转义的花括号将被显示：print(f"answer={1+variable*2}")

还有一个 index 角色用于生成索引条目。

以下角色生成外部链接

:cve:

对 常见漏洞和暴露 (Common Vulnerabilities and Exposures) 记录的引用。这会生成适当的索引条目。生成文本“CVE 编号”；并附带指向指定 CVE 在线副本的链接。您可以使用 :cve:`number#anchor` 链接到特定部分。

例如：CVE 2020-10735

版本 8.1 新增。

:cwe:

对 常见弱点枚举 (Common Weakness Enumeration) 的引用。这会生成适当的索引条目。生成文本“CWE 编号”；在 HTML 输出中，此文本是指定 CWE 在线副本的超链接。您可以使用 :cwe:`number#anchor` 链接到特定部分。

例如：CWE 787

版本 8.1 新增。

:pep:

对 Python 增强提案的引用。这会生成适当的索引条目。生成文本“PEP 编号”；在 HTML 输出中，此文本是指向指定 PEP 在线副本的超链接。您可以使用 :pep:`number#anchor` 链接到特定部分。

例如：PEP 8

:rfc:

对 Internet 征求意见书的引用。这会生成适当的索引条目。生成文本“RFC 编号”；在 HTML 输出中，此文本是指向指定 RFC 在线副本的超链接。您可以使用 :rfc:`number#anchor` 链接到特定部分。

例如：RFC 2324

请注意，没有包含超链接的特殊角色，因为您可以使用标准 reStructuredText 标记来实现此目的。

替换

文档系统提供了一些默认定义的替换。它们在构建配置文件中设置。

|release|

替换为文档所指的项目发布版本。这应该是一个完整的版本字符串，包括 alpha/beta/发布候选标签，例如 2.5.2b3。由 release 设置。

|version|

替换为文档所指的项目版本。这应该只包含主要和次要版本部分，例如 2.5，即使是版本 2.5.1 也是如此。由 version 设置。

|today|

替换为今天的日期（读取文档的日期），或构建配置文件中设置的日期。通常格式为 April 14, 2007。由 today_fmt 和 today 设置。

|translation progress|

替换为文档的翻译进度。此替换旨在供文档翻译人员用作文档翻译进度的标记。