角色¶
sphinx使用解释文本角色将语义标记插入到文档中。它们被写为 :rolename:`content '.
备注
默认角色 (`content ）默认情况下没有特殊含义。您可以随意将其用于任何您喜欢的内容，例如变量名；使用 :confval:`default_role 将其设置为已知角色的配置值-- any 查找任何内容或 py:obj 用于查找python对象的角色非常有用。
看见 领域 用于按域添加的角色。
交叉引用语法¶
看见 交叉引用语法 。
交叉引用角色包括：
内联代码突出显示¶
- :code:¶
一个 inline 代码示例。直接使用时，此角色仅显示文本 without 语法突出显示，作为字面意思。
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)显示 :abbr:`LIFO (last-in, first-out) 。Added in version 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 版本发生变更: 图形用户界面标签的快捷键可以使用与号包括在内；它将被剥离并在输出中带下划线显示(例如：
:guilabel:`&Cancel显示 :guilabel:`&Cancel )。若要包含文字与号，请将其加倍。
- :kbd:¶
标记一系列击键。按键序列采用的形式可能取决于特定于平台或应用程序的约定。当没有相关的约定时，应该拼写修饰键的名称，以提高新用户和非母语使用者的易用性。例如，一个 xemacs 按键序列可能被标记为
:kbd:`C-x C-f，但在不引用特定应用程序或平台的情况下，同一序列应标记为 `Control-x Control-f` ，显示 :kbd:`C-x C-f 和 Control-x Control-f 分别进行了分析。
- :mailheader:¶
RFC 822样式邮件标头的名称。此标记并不意味着电子邮件消息中使用了标题，但可以用来引用具有相同“样式”的任何标题。这也用于由各种MIME规范定义的标头。标头名称的输入方式应该与实际中通常使用的方式相同，在有多种常见用法的情况下，最好使用驼峰大小写约定。例如：
:mailheader:`Content-Type显示 :mailheader:`Content-Type 。
- :makevar:¶
A的名字 make
例如： help
- :manpage:¶
对包含部分的Unix手册页面的引用，例如
:manpage:`ls(1)显示 :manpage:`ls(1) 。创建指向呈现手册页的外部站点的超链接，如果manpages_url是被定义的。在 7.3 版本发生变更: 允许使用指定目标
<>，就像超链接。例如,:manpage:`blah <ls(1)>显示 :manpage:`blah <ls(1)> 。
菜单选项应使用
menuselection角色。这用于标记菜单选择的完整序列，包括选择子菜单和选择特定操作，或此类序列的任何子序列。个别选择的名称应以分隔-->.例如，要标记选择“开始>程序”，请使用以下标记：
:menuselection:`Start --> Programs`
显示：
当包含包含一些尾随指示器的选择时，例如某些操作系统用于指示命令打开对话框的省略号，应从选择名称中省略该指示器。
menuselection也支持像guilabel.
- :mimetype:¶
mime类型的名称或mime类型的组件（主要部分或次要部分，单独使用）。
例如： text/plain
- :newsgroup:¶
Usenet新闻组的名称。
例如： comp.lang.python
待处理
这不是标准域的一部分吗？
- :program:¶
可执行程序的名称。这可能与某些平台的可执行文件的文件名不同。尤其是，
.exe（或其他）对于Windows程序，应省略扩展。例如： curl
- :regexp:¶
正则表达式。不应包括报价。
例如：
([abc])+
- :samp:¶
一段文字文本，如代码。在内容中，您可以使用大括号来表示“可变”部分，如
file。例如，在:samp:`print(1+{variable})，这一部分 ``variable` 将强调：print(1+variable)如果您不需要“可变部件”指示，请使用标准的
code而不是角色。在 1.8 版本发生变更: Allowed to escape curly braces with double backslash. For example, in
:samp:`print(f"answer=\\{1+{variable}*2\\}")`, the partvariablewould be emphasized and the escaped curly braces would be displayed:print(f"answer={1+variable*2}")
还有一个 index 用于生成索引项的角色。
下列角色生成外部链接：
- :pep:¶
对Python增强建议的引用。这将生成适当的索引项。文本“PEP” 数 “生成；在HTML输出中，此文本是指向指定PEP的联机副本的超链接。你可以通过说
:pep:`number#anchor'.例如： PEP 8
- :rfc:¶
对互联网请求评论的引用。这将生成适当的索引项。文本“RFC” 数 “生成；在HTML输出中，此文本是指向指定RFC的联机副本的超链接。你可以通过说
:rfc:`number#anchor'.例如： RFC 2324
请注意，不存在包含超链接的特殊角色，因为您可以为此使用标准的REST标记。
替代品¶
文档系统提供了一些默认定义的替换。它们在生成配置文件中设置。
- |release|
由项目发布替代，文件参考。这是一个完整的版本字符串，包括alpha/beta/release候选标记，例如
2.5.2b3. 通过设置release.
- |version|
替换为文档引用的项目版本。这意味着只包含主要和次要版本的部分，例如
2.5，即使是2.5.1版。通过设置version.
- |translation progress|
替换为文档的翻译进度。此替换旨在供文档翻译人员用作文档翻译进度的标记。