角色

Sphinx使用解释文本角色将语义标记插入文档.它们的写法为``:rolename:content` .

备注

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

请参见 域 以获取域添加的角色.

交叉引用语法

请参见 交叉引用语法 .

交叉引用角色包括:

内联代码高亮

:code:

一个 内联 代码示例.当直接使用时,此角色仅以文字的形式显示文本 而不 进行语法高亮.

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

显示: 默认情况下,内联代码例如:code: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`.

Displays: 自毕达哥拉斯以来,我们知道 \(a^2 + b^2 = c^2\) .

:eq:

与 math:numref 相同.

其他语义标记

以下角色除了以不同风格格式化文本外,不执行任何其他操作:

:abbr:

一个缩写.如果角色内容包含括号说明,将特别处理:在HTML中以工具提示显示,并在LaTeX中只输出一次.

例如:``LIFO .

Added in version 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标签的加速键可以使用&包含;这将在输出中被去除并显示为下划线（例如:``Cancel```显示为 :guilabel:`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 规范定义的头部.头部名称应以通常在实践中找到的方式输入,当存在多种常用用法时,优先使用驼峰命名法.例如:``Content-Type```显示 :mailheader:`Content-Type .

:makevar:

一个 make 变量的名称.

例如: help

:manpage:

对Unix手册页的引用,包括章节,例如``:manpage:ls(1)```显示 :manpage:`ls(1) .如果定义了 manpages_url ,则创建一个超链接到外部网站以呈现手册页.

在 7.3 版本发生变更: 允许使用 <> 指定目标,类似于超链接.例如,``:manpage:blah <ls(1)>```显示 :manpage:`blah <ls(1)> .

:menuselection:

菜单选择应使用 menuselection 角色标记. 这用于标记一整个菜单选择序列,包括选择子菜单和选择特定操作,或该序列的任何子序列. 各个选择的名称应使用 --> 分隔.

例如,要标记选择 “开始 > 程序”,请使用此标记:

:menuselection:`Start --> Programs`

显示: 开始 ‣ 程序

当包含某个选择时,如果该选择包含一些尾部指示符,例如某些操作系统使用的省略号来表示该命令会打开一个对话框,则该指示符应从选择名称中省略.

menuselection also supports ampersand accelerators just like 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 编号";在 HTML 输出中,这段文本是指向指定 RFC 在线副本的超链接.您可以通过说``:rfc:`编号#锚点``来链接到特定部分.

例如: RFC 2324

注意,在包含超链接时没有特殊角色,因为您可以使用标准的reStructuredText标记来实现这一目的.

替换符

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

|release|

被项目发布所替代,文档所指的. 这应该是包含 alpha/beta/候选发布标签的完整版本字符串,例如 2.5.2b3 . 由 release 设置.

|version|

被文档所引用的项目版本替代.这应仅由主版本和次版本部分组成,例如 2.5 ,即使是版本 2.5.1.由 version 设置.

|today|

替换为今天的日期（文档被查看的日期）,或构建配置文件中设置的日期.通常格式为 2007年4月14日 .由 today_fmt 和 today 设置.

|translation progress|

被文档的翻译进度替代.此替代品旨在供文档翻译人员使用,作为文档翻译进度的标记.