角色¶

Sphinx使用解释的文本角色将语义标记插入到文档中。它们被写成 :rolename:`content `。

备注

默认角色 (`content )默认情况下没有特殊含义。您可以自由地将其用于任何您喜欢的用途，例如变量名称；使用 :confval:`default_role 配置值将其设置为已知角色-- any 角色来查找任何内容或 py:obj 角色来查找Python对象对此非常有用。

看到域对于域添加的角色。

交叉引用¶

看到交叉引用 .

交叉引用角色包括：

any
doc
download
envvar
keyword
numref
option (and已弃用的 cmdoption )
ref
term
token

内联代码突出显示¶

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

对象的名称 make 变量。

例如： help

:manpage:¶: 对包含部分的Unix手册页面的引用，例如 :manpage:`ls(1) 显示 :manpage:`ls(1) 。创建指向呈现手册页的外部站点的超链接，如果 manpages_url 是被定义的。

在 7.3 版本发生变更: 允许指定目标 <> 比如超链接。例如， :manpage:`blah <ls(1)> '显示 blah .

:menuselection:¶

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

例如，要将选择标记为“开始>程序”，请使用以下标记：：

:menuselection:`Start --> Programs`

显示： 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 part variable would be emphasized and the escaped curly braces would be displayed: print(f"answer={1+variable*2}")

还有一个 index 角色来生成索引项。

以下角色生成外部链接：

:cve:¶

提述 Common Vulnerabilities and Exposures 记录这将生成适当的索引条目。文本“UTE number ”已生成;带有指向指定UTE在线副本的链接。您可以使用链接到特定部分 :cve:`number#anchor `.

例如： CVE 2020-10735

Added in version 8.1.

:cwe:¶

提述 Common Weakness Enumeration .这将生成适当的索引条目。文本“CWE number “;在HTML输出中，带有指向指定CWE的在线副本的链接。您可以使用链接到特定部分 :cwe:`number#anchor `.

例如： CWE 787

Added in version 8.1.

:pep:¶

对一项Python增强建议的引用。这将生成适当的索引项。正文《PEP》 number “生成；在HTML输出中，此文本是指向指定PEP的在线副本的超链接。您可以通过以下方式链接到特定部分 :pep:`number#anchor `。

例如： PEP 8

:rfc:¶

对互联网请求评论的引用。这将生成适当的索引项。文本“RFC” number 在HTML输出中，此文本是指向指定RFC的在线副本的超链接。您可以通过以下方式链接到特定部分 :rfc:`number#anchor `。

例如： RFC 2324

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

替换¶

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

|release|: 替换为文档所指的项目版本。这是包括Alpha/Beta/Release候选标签的完整版本字符串，例如 2.5.2b3 。设置者 release 。

|version|: 替换为文档引用的项目版本。这意味着只包含主要版本和次要版本部分，例如 2.5 ，即使对于版本2.5.1也是如此。设置者 version 。

|today|: 替换为今天的日期(读取文档的日期)或生成配置文件中设置的日期。通常具有以下格式 April 14, 2007 。设置者 today_fmt 和 today 。

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