角色

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:

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

例如：二进制模式

: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 角色来生成索引条目。

以下角色生成外部链接

:pep:

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

例如：PEP 8

:rfc:

对互联网请求意见书的引用。这会生成相应的索引条目。生成“RFC number”文本；在 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|

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