角色

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:

操作系统级别命令的名称，例如 rm。

例如： rm

:dfn:

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

例如： binary mode

: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:

对 通用漏洞和披露 记录的引用。 这会生成适当的索引条目。 生成文本 “CVE 编号”； 并链接到指定 CVE 的在线副本。 您可以使用 :cve:`number#anchor` 链接到特定部分。

例如： CVE 2020-10735

在 8.1 版本中新增。

:cwe:

对 通用弱点枚举 的引用。 这会生成适当的索引条目。 生成文本 “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|

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