角色¶
Sphinx使用解释文本角色将语义标记插入到文档中。它们被写成 :rolename:`content`。
备注
默认角色（`content`）在默认情况下没有特殊含义。您可以将其用于任何您喜欢的用途，例如变量名；使用 default_role 配置值将其设置为已知角色 -- 比如 any 角色用于查找任何内容或 再如 py:obj 角色用于查找Python对象，非常有用。
参见 域 了解域添加的角色。
交叉引用¶
参见 交叉引用。
交叉引用角色有：
行内代码高亮¶
- :code:¶
内联 代码示例。直接使用时，此角色仅显示 不带 语法高亮的文本，仅作为文字来显示。
By default, inline code such as :code:`1 + 2` just displays without highlighting.
显示为： By default, inline code such as
1 + 2just displays without highlighting.与
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`.
显示为：Since Pythagoras, we know that \(a^2 + b^2 = c^2\)。
- :eq:¶
Same as
math:numref.
其他语义标记¶
以下角色除了以不同的样式格式化文本外，不会执行任何特殊操作：
- :abbr:¶
缩写。如果角色内容包含带圆括号的解释，则将对其进行特殊处理：它将在HTML的工具提示中显示，在LaTeX中仅输出一次。
例如
:abbr:`LIFO (last-in, first-out)`显示为 LIFO。（注意，鼠标悬停在LIFO上时会显示last-in, first-out）在 0.6 版本加入.
- :command:¶
操作系统级命令的名称比如
rm。例如：
:command:`rm`显示为 rm
- :dfn:¶
标记文本中术语的定义实例。（不生成索引项。）
例如
:dfn:`binary mode`显示为 binary mode
- :file:¶
文件或目录的名称。在内容中，可以使用大括号表示“变量”部分，例如：
... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...显示为：... is installed in
/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 manual page的引用，包括章节，比如
:manpage:`ls(1)`显示为 ls(1)。如果定义了manpages_url，则创建超链接，指向呈现manpage的外部站点。在 7.3 版本发生变更: 允许使用
<>指定目标，就像超链接一样。例如，:manpage:`blah <ls(1)>`显示为 blah。
应使用
menuselection角色标记菜单选择。这用于标记完整的菜单选择序列，包括选择子菜单和选择特定操作，或此类序列的任何子序列。单个选择的名称应以-->分隔。例如，要标记选择"Start > Programs"，请使用以下标记：
:menuselection:`Start --> Programs`
显示为：
有些菜单选项包含尾随指示符（例如某些操作系统用省略号来指示命令会打开对话框），在描述这些菜单选项时，应从选项名称中省略该指示符。
menuselection还支持与号快捷键，像guilabel一样。
- :mimetype:¶
MIME类型的名称，或MIME类型的组件（主要部分或次要部分，单独使用）。
例如： text/plain
- :newsgroup:¶
Usenet新闻组的名称。
例如： comp.lang.python
- :program:¶
可执行程序的名称。对于某些平台，这可能与可执行文件的文件名不同。特别是对于Windows程序，应该省略
.exe（或其他）扩展名。例如： curl
- :regexp:¶
正则表达式。不应包括引号。
例如：
:regexp:`([abc])+`显示为([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 number"；并链接到指定CVE的在线副本。您可以通过
:cve:`number#anchor`来链接到特定的章节。例如： CVE 2020-10735
在 8.1 版本加入.
- :cwe:¶
对 Common Weakness Enumeration 的引用。这将生成适当的索引项。生成文本 "CWE number"；在HTML输出中，并链接到指定CWE的在线副本。您可以通过
:cwe:`number#anchor`来链接到特定的章节。例如： CWE 787
在 8.1 版本加入.
- :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/release候选标记，例如“2.5.2b3”。设置者
release。
- |version|
替换为文档所引用的项目版本。这意味着只包含主要版本和次要版本部分，例如“2.5”，即使对于版本2.5.1也是如此。设置者
version。
- |translation progress|
替换为文档的翻译进度。此替代品旨在供文档翻译人员用作文档翻译进度的标记。