角色

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

备注

默认角色（“content”）在默认情况下没有特殊含义。您可以将其用于任何您喜欢的用途，例如变量名；使用：confval:`default_role`配置值将其设置为已知角色–rst:角色：`any`角色查找任何内容或：rst:角色用于查找Python对象的：`py:obj`角色对此非常有用。

See 域 for roles added by domains.

交叉引用语法

See 交叉引用语法.

Cross-reference roles include:

Inline code highlighting

:code:

An inline code example. When used directly, this role just displays the text without syntax highlighting, as a literal.

By default, inline code such as :code:`1 + 2` just displays without
highlighting.

Displays: By default, inline code such as 1 + 2 just displays without highlighting.

Unlike the code-block directive, this role does not respect the default language set by the highlight directive.

To enable syntax highlighting, you must first use the Docutils role directive to define a custom role associated with a specific language:

.. role:: python(code)
   :language: python

In Python, :python:`1 + 2` is equal to :python:`3`.

To display a multi-line code example, use the code-block directive instead.

数学

:math:

内联数学的角色。这样使用：

Since Pythagoras, we know that :math:`a^2 + b^2 = c^2`.

Displays: Since Pythagoras, we know that \(a^2 + b^2 = c^2\).

:eq:

Same as math:numref.

其他语义标记

以下角色除了以不同的样式格式化文本外，不会执行任何特殊操作：

:abbr:

缩写。如果角色内容包含带圆括号的解释，则将对其进行特殊处理：它将在HTML的工具提示中显示，在LaTeX中仅输出一次。

For example: :abbr:`LIFO (last-in, first-out)` displays LIFO.

Added in version 0.6.

:command:

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

For example: rm

:dfn:

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

For example: binary mode

:file:

文件或目录的名称。在内容中，可以使用大括号表示“变量”部分，例如：

... is installed in :file:`/usr/lib/python3.{x}/site-packages` ...

Displays: … is installed in /usr/lib/python3.x/site-packages …

在生成的文档中，“x”将以不同的方式显示，以指示它将被Python次要版本所取代。

:guilabel:

作为交互用户界面一部分的标签应该用“guilabel”来标记。这包括来自基于文本的接口的标签，例如使用：mod:`curses`或其他基于文本的库创建的标签。在界面中使用的任何标签都应该标记此角色，包括按钮标签、窗口标题、字段名称、菜单和菜单选择名称，甚至选择列表中的值。

在 1.0 版本发生变更: An accelerator key for the GUI label can be included using an ampersand; this will be stripped and displayed underlined in the output (for example: :guilabel:`&Cancel` displays Cancel). To include a literal ampersand, double it.

:kbd:

Mark a sequence of keystrokes. What form the key sequence takes may depend on platform- or application-specific conventions. When there are no relevant conventions, the names of modifier keys should be spelled out, to improve accessibility for new users and non-native speakers. For example, an xemacs key sequence may be marked like :kbd:`C-x C-f`, but without reference to a specific application or platform, the same sequence should be marked as :kbd:`Control-x Control-f`, displaying C-x C-f and Control-x Control-f respectively.

:mailheader:

The name of an RFC 822-style mail header. This markup does not imply that the header is being used in an email message, but can be used to refer to any header of the same “style.” This is also used for headers defined by the various MIME specifications. The header name should be entered in the same way it would normally be found in practice, with the camel-casing conventions being preferred where there is more than one common usage. For example: :mailheader:`Content-Type` displays Content-Type.

:makevar:

命令名：make variable。

For example: help

:manpage:

A reference to a Unix manual page including the section, e.g. :manpage:`ls(1)` displays ls(1). Creates a hyperlink to an external site rendering the manpage if manpages_url is defined.

在 7.3 版本发生变更: Allow specifying a target with <>, like hyperlinks. For example, :manpage:`blah <ls(1)>` displays blah.

:menuselection:

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

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

:menuselection:`Start --> Programs`

Displays: Start ‣ Programs

当包含包含某些尾随指示符的选择（例如某些操作系统用于指示命令打开对话框的省略号）时，应从选择名称中省略该指示符。

“menuselection”还支持与号和加速器，就像：rst:role:guilabel。

:mimetype:

MIME类型的名称，或MIME类型的组件（主要部分或次要部分，单独使用）。

For example: text/plain

:newsgroup:

Usenet新闻组的名称。

For example: comp.lang.python

待处理

这不是标准域的一部分吗？

:program:

可执行程序的名称。对于某些平台，这可能与可执行文件的文件名不同。特别是，对于Windows程序，应该省略“.exe”（或其他）扩展名。

For example: curl

:regexp:

正则表达式。不应包括引号。

For example: ([abc])+

:samp:

A piece of literal text, such as code. Within the contents, you can use curly braces to indicate a “variable” part, as in file. For example, in :samp:`print(1+{variable})`, the part variable would be emphasized: print(1+variable)

If you don’t need the “variable part” indication, use the standard code role instead.

在 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}")

还有一个:rst:role:`index`角色生成索引项。

以下角色生成外部链接：

:pep:

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

For example: PEP 8

:rfc:

对互联网征求意见的引用。这将生成适当的索引项。生成文本“RFC*number*”；在HTML输出中，此文本是指向指定RFC联机副本的超链接。您可以通过说“:rfc:`number#anchor`”来链接到特定的部分。

For example: RFC 2324

请注意，对于包含超链接没有特殊的角色，因为您可以使用标准reST标记来实现这一目的。

替代品

The documentation system provides some substitutions that are defined by default. They are set in the build configuration file.

|release|

替换为文档所指的项目版本。这意味着是完整的版本字符串，包括alpha/beta/release候选标记，例如“2.5.2b3”。设置者 release。

|version|

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

|today|

替换为今天的日期（读取文档的日期）或生成配置文件中设置的日期。通常格式为“2007年4月14日”。设置者：confval:today_fmt`和：confval:`today。

|translation progress|

Replaced by the translation progress of the document. This substitution is intended for use by document translators as a marker for the translation progress of the document.