发布于 2015-09-16 15:42:19 | 450 次阅读 | 评论: 0 | 来源: 网络整理
Sphinx 使用文本解释角色在文档中插入语义标签. 这样写 :rolename:`content`.
Note
默认角色 (`content`) 并不特别. 可使用任何其他有效的名字来代替; 使用 :confval:`default_role` 设置.
由主域添加的角色请参考 Sphinx Domains .
多数文本解释角色都会产生交叉索引. 需要写一个 :role:`target`, 创建名为 target 的链接，类型由 role 指定. 链接文本与 target 一样.
还有其他的功能，这使得交叉索引更通用:
需要明确的标题及索引标签, 像reST 超链接: :role:`title <target>` ，会链接 target 标签, 但链接文本为 title.
加前缀 !, 交叉索引/超链接不会被创建.
前缀 ~, 链接文本仅是标签的最后成分. 例如, :py:meth:`~Queue.Queue.get` 会建立到 Queue.Queue.get 的链接，但是链接文本仅显示 get .
HTML 文档, 链接的 title 属性 (显示为鼠标的tool-tip) 一直是完整的标签名.
:ref:在文档的任意位置都可以使用交叉索引, 像标准reST 标签一样使用. 对于文档条目这些标签名必须是唯一的.有两种方式可以链接到这些标签:
< >标签直接放在章节标题前面, 可以通过 :ref:`label-name` 引用.例如:
.. _my-reference-label: Section to cross-reference -------------------------- 章节内容. 需引用自身, 查看 :ref:`my-reference-label`.
角色 :ref: 会产生这个章节的链接, 链接标题是 “Section to cross-reference”. 章节与索引可在不同的源文件.
自动标签也可以使用 figures: given
.. _my-figure: .. figure:: whatever Figure caption
参考 :ref:`my-figure` 将在图例里插入引用索引，链接文本是 “Figure caption”.
表格也可以使用，在表格标题上使用指令 :dudir:`table` .
标签不放在章节开头，需要给出明确的链接，使用语法: :ref:`Link title <label-name>`.
ref 而不是标准的reStructuredText 章节链接 (比如 `Section title`_) ，因为它可以在不同文件间使用，并且即使章节标题变化，所有的生成器仍支持这些索引.
New in version 0.6.
可以直接链接到文档名.
:doc:链接到指定文档; 文档名可以是绝对或相对的. 例如, 参考 :doc:`parrot` 出现在文档 sketches/index``中, 将会链接到文档 ``sketches/parrot. 如果参考是 :doc:`/people` 或 :doc:`../people`, 将会链接到文档 people.
如果没有给出链接标题(使用: :doc:`Monty Python members </people>`), 链接标题就是文档的标题.
New in version 0.6.
:download:该角色可以链接源目录里可以浏览、但不是reST格式的文档，这些文件将被下载.
如果使用该角色，被参考的文件会自动包含到输出里(显然仅是HTML输出). 可下载文件被放在输出目录的子目录 _downloads 里;文件名被复制.
示例:
查看 :download:`this example script <../example.py>`.
文件名是当前路径的相对路径, 绝对路径则被认为以源目录为根目录的相对路径.
文件 example.py 被复制到输出目录, 并生成链接.
以下角色也会生成索引, 但不对应实体:
:envvar:环境变量. 会生成索引. 也会产生到指令 envvar 的链接，如果指令存在.
:token:语法名子 (用来产生到指令 productionlist 的链接).
:keyword:Python的关键字. 会创建这些关键字的链接.
:option:执行程序的命令行参数. 需包含连字号开头. 产生到指令 option 的链接.
以下角色产生术语的索引:
:term:术语索引. 术语由指令 glossary 创建，包含一列术语的定义. 在同一文件里不能使用 term 标记, Python 文档有一个全局的术语文件 glossary.rst.
如果使用的术语不在术语表里, 将会产生警告.
下面的这些角色以不同样式格式化文本:
:abbr:缩写应用. 如果角色后有个括号说明文字，在HTML时会显示成 tool-tip ,仅在LaTeX才会输出.
例如: :abbr:`LIFO (last-in, first-out)`.
New in version 0.6.
:command:系统级别的命令，例如 rm.
:dfn:在文本中标记术语定义. (不产生索引条目)
:file:文件或目录名. 可以使用花括号指示变量部分, 例如:
... is installed in :file:`/usr/lib/python2.{x}/site-packages` ...
在生成文档时, x 会被Python 的次要版本号替换.
:guilabel:表示用户交互接口的标签需使用 guilabel 标记. 包含基于文本的接口如 使用 curses 创建的或基于其他文本库的标签. 接口标签必须使用该角色标记， 包括按钮，窗口标题，文件名，菜单，菜单选项，甚至选择列表里的值.
Changed in version 1.0: GUI 标签可以使用&标示快捷方式; 输出时&不会显示，而是在文本下面加下划线 (例如: :guilabel:`&Cancel`). 要在输出是包含&，则使用两个&&.
:kbd:标记键值序列. 键值序列一般依赖于平台或特定应用程序的约定. 如果没有相关的约定, 键值序列的名字应该可以修改, 以改善新用户或非英语系使用者的体验. 例如, 一个 xemacs 键序被标记为 :kbd:`C-x C-f`, 如果没有特定应用程序或平台可供参考， 则同样的键序应该被标记为 :kbd:`Control-x Control-f`.
:mailheader:RFC 822-样式邮件头的名字. 该标记并不表明邮件头在邮件信息里使用, 而是被用来映射所有相同样式的邮件头. 也被用来定义有邮件头的MIME类型. 在实践中邮件头名通常以相同的方式键入, 遵循 camel-casing 约定， 有多种通用用法时被优选采用. 例如: :mailheader:`Content-Type`.
:makevar:命令 make 的变量名.
:manpage:参考 Unix 手册页，包含章节,例如 :manpage:`ls(1)`.
菜单选项由角色 menuselection 标记. 标记完整的菜单选项序列，包含子菜单和选择的特定操作，以及所有的子序列. 独立选项的名字使用 --> 分隔.
例如，标记选项 “Start > Programs”:
:menuselection:`Start --> Programs`
选项如果包含一些指示, 例如某些操作系统会使用一些标志指示命令会打开一个对话框, 这些指示信息在选项名中会被忽略.
menuselection 也支持&, 与 guilabel 一样使用.
:mimetype:MIME 类型, 或者MIME 类型的元素 (主要次要部分可以分开).
:newsgroup:Usenet 新闻组.
:program:执行程序脚本. 与某些平台的可执行文件名不同, 比如Windows 程序的 .exe (或其他) 扩展名会被忽略.
:regexp:正则表达式，不包括引用.
:samp:一块字面量文本，如代码. 文本内可以有花括号变量，如在 file 一样. 例如, 在 :samp:`print 1+{variable}`, variable 的部分会被强调.
如不需要变量部分，使用标准代码即可.
角色 index 会产生索引条目.
下面的角色会产生外部链接:
:pep:对Python Enhancement Proposal 的参考. 会产生适当的索引条目及文本 “PEP number” ; 在HTML 文档,该文本是指向在线PEP文档的超链接. 可以链接到特定章节 :pep:`number#anchor`.
:rfc:Internet Request for Comments的参考. 也会产生索引条目及文本 “RFC number” ; 在HTML文档里是一个超链接，指定链接章节 :rfc:`number#anchor`.
如果没有特定的角色能够包含需要的超链接，就使用标准reST 标记.
文档系统提供三种默认定义的替换，可在配置文件里设置.
|release|被项目文档的发布版本替换. 这时版本字符串包含完整的标签 alpha/beta/release ,例如 2.5.2b3. 由 :confval:`release` 设置.
|version|被项目文档的版本替换. 版本字符串仅有主要和次要两部分组成，例如版本2.5.1会表示为 2.5. 由 :confval:`version` 设置.
|today|替换今天的日期 (文档被读取的日期), 或者配置文件设置的日期. 默认格式为 April 14, 2007. 可设置 :confval:`today_fmt` 及 :confval:`today` .