Python 3 文档(简体中文) 3.2.2 documentation

Version: 3.2.2

4. 额外的标记

除了标准 reST 的标记, Sphinx 增加了很多的控制指令和解释的文字. 本节将包含一个参考手册, 对此进行具体描述. “标准” 的 reST 文档是不会在这里介绍的, 尽管他们会在 Python 文档中用到.

Note

这个仅仅是对 Sphinx 扩展标记的一个概述; 完全的参考手册可以在 它自己的文档 中找到.

4.1. 元信息标记

sectionauthor

本节作者的标识符. 参数应该包含作者的名字和邮箱地址. 而地址的域名应该是小写的. 例如:

.. sectionauthor:: Guido van Rossum <guido@python.org>

目前, 这个标记并没有在输出时有什么反映, 但是它记录了谁对此有贡献.

4.2. 关于模块的标记

这个标记描述了关于文档中模块的相关信息. 每个模块都应该在自己的文件中描述. 一般来说, 这个标记出现在文件的标题后面; 一个典型的文件会看起来像这样:

:mod:`parrot` -- Dead parrot access
===================================

.. module:: parrot
   :platform: Unix, Windows
   :synopsis: Analyze and reanimate dead parrots.
.. moduleauthor:: Eric Cleese <eric@python.invalid>
.. moduleauthor:: John Idle <john@python.invalid>

就像你看到的, 关于模块的标记包含有两个指令, 一个是 module , 另一个 moduleauthor 指令.

module

这个指令标记了模块, 包, 或子模块的描述. 这个名字应该完整 ( 也就是说对于子模块应该包含包名) .

platform 选项, 如果存在, 是一个用逗号分隔的列表, 这个指明了能够使用该模块的平台 (如果在所有平台都可以使用, 那么就应该忽略这个选项). 而此处使用的应该是简短的标识符; 比如 “IRIX”, “Mac”, “Windows”, and “Unix”. 使用正确的键值是很重要的.

synopsis 选项应该包含一个模块目的的描述 – 目前这个只用于全局模块索引.

deprecated 选项可以使用 (而不需要值) 用于标记一个模块是被反对的; 它将会在合适的地方被指定.

moduleauthor

moduleauthor 指令, 可以多次出现, 指明了模块编写者, 就像 sectionauthor 指明了文档的作者一样. 这个同样也没有任何输出.

Note

下面这点很重要, 每个模块的章节标题应该有意义, 因为这个将被插入到目录中.

4.3. 信息单元

在模块中会有很多用以特殊作用的指示符. 每个指示符都需要一个甚至更多的签名 用于提供基本的信息, 而其内容应该是具体的描述. 最基本的版本应该是有索引的; 如果没有索引, 那么你可以给指示符一个选项 :noindex:. 下面的例子给出了所有的特征:

.. function:: spam(eggs)
              ham(eggs)
   :noindex:

   Spam or ham the foo.

对象的方法或成员的签名应该总包含其类型的名称 (.. method:: FileInput.input(...)), 尽管它可能是从上下文中很容易看出; 这个就可以使用交叉引用了. 如果你描述的方法属于一个抽象的协议, 像 “context managers”, 同样请包含一个 (伪) 类型名用以在索引中给出更多信息.

The directives are:

c:function

描述一个 C 的函数. 其签名应该是以 C 的形式给出, 比如:

.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject * type, Py_ssize_t nitems)

同样, 这也可以用于描述类似函数的预处理宏. 参数的名称也应该给出, 这样可以方便下面的描述.

注意, 你不需要在签名中使用反斜杠来转义星号, 因为此处的不会被 reST 处理. ( 译者注: 当然, 如果你不放心, 可以在星号两边留下一个空格. )

c:member

描述 C 结构体的成员. 像下面的签名:

.. c:member:: PyObject* PyTypeObject.tp_bases

此处的描述应该包含值所允许的范围, 这个值是如何被解释的, 以及这个值能否改变. 引用这个结构体的成员需要使用 member .

c:macro

描述一个 “简单的” C 宏. 简单的宏就是那些用于代码扩展, 但是不接受参数的宏. 这个不会用于简单的常量定义. 举个例子, 使用的有 PyObject_HEADPy_BEGIN_ALLOW_THREADS .

c:type

描述一个 C 的类型. 签名就是这个类型名.

c:var

描述一个全局的 C 变量. 这个签名应该包含其类型, 像这样:

.. cvar:: PyObject* PyClass_Type
data

描述一个模块中的全局数据, 包括变量和那些当作常量的值. 类和对象的属性不应该在此环境中出现.

exception

描述一个异常类. 这个签名可以, 但不需要包含构造是的参数及括号.

function

描述一个模块级别的函数. 签名应该包含参数, 以方括号括起的可选参数. 默认的值可以给出. 例如:

.. function:: Timer.repeat([repeat=3[, number=1000000]])

对象的方法不应该在此处使用. 作为模块命名空间中的接口的绑定对象的方法, 应该使用这个, 因为大多时候它们与普通的函数相同.

描述的信息应该包含如所需参数的信息, 它们如何被使用 (特别是那些对象被出过去后, 能否被改变), 副作用, 和可能的异常. 也应该提供一个简单的例子.

decorator

描述一个修饰器函数. 此签名不应该给出真实函数的签名, 但是需要给出作为一个修饰器应该如何使用. 举个例子给这样的函数

def removename(func):
    func.__name__ = ''
    return func

def setnewname(name):
    def decorator(func):
        func.__name__ = name
        return func
    return decorator

而其描述应该这样子:

.. decorator:: removename

   移除被修饰函数的名程

.. decorator:: setnewname(name)

   设置被修饰的名称为 *name*.

在此处, 没有 deco 这样的东西可以直接链接到一个修饰器; 但你可以使用 :func: .

class

描述一个类. 这个签名应该包含构造时所需的参数.

attribute

描述一个对象的数据属性. 此处的描述应该包含数据所需的类型, 以及是否可以直接改变.

method

描述一个对象的方法. 参数无须包含 self. 其描述和 function 类似就可以了.

decoratormethod

decorator 一样,但是修饰的是方法.

引用修饰器方法要使用 :meth: .

opcode

描述 Python 的 bytecode .

cmdoption

描述 Python 命令行选项. 选项参数的名称需要以尖括号括起来. 例子:

.. cmdoption:: -m <module>

   Run a module as a script.
envvar

描述一个 Python 使用或定义的环境变量.

还有指示符的普遍版本:

describe

这个指示符和前面所说的产生的格式化效果一样, 但是 不会 创建索引项 或是交叉引用. 这一般用于描述文档中的指示符. 比如:

.. describe:: opcode

   Describes a Python bytecode instruction.

4.4. 显示示例代码

Python 的源码或者是交互的会话都以 reST 的 literal block 来表示. 通过 :: 开头, 然后内容要进行缩进, 最后以同级的缩进表示结束.

交互式会话的表示需要包含提示和输出. 此处不需要特殊的标记. 在输入和输出结束后, 最后一行不要放上一个未使用的提示符; 下面是一个不要那样的例子:

>>> 1 + 1
2
>>>

语法的高亮会以一种智能的方式处理:

对于每个文档源文件, 都会有一个 “高亮的语言” . 在此处, 默认的都是设为 Python.
  • 在 Python 高亮的模式下, 交互会话会被自动识别并且进行合适的高亮.

  • 高亮的语言可以使用 highlightlang 进行控制, 像下面这样使用:

    .. highlightlang:: c
    

    这样这个语言就会被使用了, 直到遇到下一个 highlightlang 为止.

  • 一般会用到的:

    • python (the default)
    • c
    • rest
    • none (no highlighting)
  • 如果以某种语言高亮失败了, 那么这个块就不被任何形式高亮.

如果在使用时需要很大篇幅的源代码, 我们可以使用额外导入的方式将代码引入进来. 需要导入的文件可以使用 literalinclude 指示符导入. [1] 举个例子, 要导入一个 Python 源码 example.py , 使用:

.. literalinclude:: example.py

这个文件的路径是相对于当前文件的路径的. 包含的文件最好放到 Doc/includes 下面.

4.5. 行内标记

在前面也说过, Sphinx 使用特殊的标记来指明语义.

一个局部变量的名字, 比如函数/方法的参数, 它们是一个例外, 只需要用星号括起来即可, 如 *var* .

对于其他的, 你需要写 :rolename:`content`.

有一些额外的设施可以以多种方式使交叉引用:

  • 你可以提供一个显式的标题及一个引用对象, 像 reST 中直接的超链接: :role:`title <target>` 将会指向 target, 但是链接显示的会是 title.

  • 如果你在内容前面加了个 !, 那么将不会创建引用/链接.

  • 对于 Python 对象来说, 如果你在内容前面放上一个 ~, 链接的文字将只是最后一个. 比如 :meth:`~Queue.Queue.get` 将会指向 Queue.Queue.get, 但是将只显示 get .

    在输出的 HTML 中, 链接的 title 属性 (也就是在你将鼠标放到链接上时, 显示的文字) 将永远是全名.

下面的将会指向一个模块中的对象, 并且如果有匹配的标识符就会生成超链接:

mod

模块的名称; 有点的名称将被使用. 同样这也用于一个包名称.

func

一个 Python 函数的名称; 有点的名称可以使用. 这里所用的内容不应该包含后面的括号. 当搜索标识符时, 后面的括号是被去除了的.

data

模块级别的变量或常量的名称.

const

一个定义过的常量的名称. 它可能是 C 语言中的 #define 或是 Python 中设为不可变的变量.

class

一个类名; 可以使用有点的名称.

meth

一个对象方法的名称. 此处应该包括类型名和方法名. 有点的也可以使用.

attr

一个对象的数据属性.

exc

一个异常的名称. 有点的可以使用.

在这些标记中的名称可以包含一个模块名 和/或 一个类名称. 举个例子, :func:`filter` 可以指向一个名为 filter 的函数, 或者指向内置的函数. 相反, :func:`foo.filter` 很明确的指向 foo 模块中的 filter 函数.

一般的, 这些名称将会先没有限制的搜索, 然后考虑当前的模块, 然后是当前的模块和类. 如果你用有一个点号的前缀, 那么顺序会反转. 举个例子, 在 codecs 这个模块的文档中, :func:`open` 将总是指向内置的函数, 而 :func:`.open` 将指向 codecs.open().

一个类似的启发也用于决定当前的名称是否是当前编写文档类的属性.

下面的这些将会创建到 C 语言的交叉引用, 前提是在 API 文档中有定义:

c:data

C 中变量的名称.

c:func

C 中的函数. 需要包含后面的括号.

c:macro

一个简单的宏的名称, 像前面那样定义.

c:type

C 中类型的名称.

c:member

C 中类型的成员.

下面的会创建交叉引用, 但是不会指向对象:

token

语法表示的名称 (在参考手册中创建链接).

下面的会创建交叉引用至单词表中的一项:

term

指向单词表中的一项. 单词表在使用 glossary 指示符后会创建出来. 不需要再每个文件中都创建一个, 事实上, Python 文档默认就有个全局 的单词表, 就在 glossary.rst 文件中.

如果你使用了 term 但是却没有在单词表中解释, 在建立时你将得到一个警告.


后面的则不会做任何特殊的处理, 除了以不同的样式格式化文本:

command

系统级别的命令, 比如 rm.

dfn

标记一个术语的定义实例. (不会有索引项生成.)

envvar

一个环境变量. 将生成索引项.

file

一个文件或目录的名称. 在内容中, 你可以使用大括号表示可变的部分, 举个例子:

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

在建立文档时, x 将会以不同的样子显示, 以表示区别.

guilabel

作为交互式用户界面的标签应该使用 guilabel 标记. 这包括基于文本的界面, 像使用 curses 或其他库创建的. 任何标签都应该以此标记, 包括按钮的, 窗口标题的, 域的名字, 菜单和菜单选择项, 以及选择列表中的值.

kbd

标记一系列的按键. 使用什么样的按键要取决于平台或程序的约定. 当没有相关的约定, 修饰的按键应该全拼, 以提高可读性. 举个例子, 一个 xemacs 的按键可以标记为 :kbd:`C-x C-f`, 但是如果没有其他的相关性, 就应该写为 :kbd:`Control-x Control-f`.

keyword

在 Python 中的关键词.

mailheader

一个 RFC 822 式的邮件头名称. 这个标记没有暗指在邮件消息中被使用的头, 但是可以指示它们的样式. 这也用于那些 MIME 的值. 头的名称应该是以相同的方式输入, 并且应该按约定来使用. 举个例子: :mailheader:`Content-Type`. (译注: 不是很明白)

makevar

make 变量的名称.

manpage

Unix 上的参考手册, 包括那一节, 比如 :manpage:`ls(1)`.

menuselection

菜单的选择应该用 menuselection 来标记. 这用于标记一个完整的菜单选择项, 包括选择子菜单和选择特殊的操作, 或者是任何的一个子序列. 不同的选项之间应该以 --> 分割.

比如, 要标记 “开始 > 程序”, 那么就用:

:menuselection:`开始 --> 程序`

一个 MIME 类型的名字, 或者一个部分 (主要或最小的部分).

newsgroup

一个 Usenet newsgroup 的名称.

option

一个命令行的选项. 选项前的横线必须要包括进来. 如果匹配到 cmdoption , 那么就会自动链接过去. 对于其他语言或脚本, 使用 ``code`` 标记.

program

可执行程序的名称. 这在不同的平台上, 可能会有所不同. 特别像在 Windows 平台, 后缀 .exe 就可以省略.

regexp

一个正则表达式. 引号不需要包括.

samp

一个片段, 像代码之类. 在内容中, 你可以使用尖括号表示变的部分, 像在 :file: 中一样.

如果你不需要可变的, 那么久使用 ``code`` 替代.

下面的用于产生外部链接:

pep

指向 Python Enhancement Proposal . 这将生成一个合适的索引项. 将会生成如 “PEP number” 的文字; 在 HTML 输出的结果中, 这个文字会链接到特定的 PEP 上.

rfc

指向 Internet Request for Comments . 这也产生合适的索引项. 生成入 “RFC number” 的文字; 在 HTML 输出的结果中, 这个文字会链接到特定的 RFC 上.

注意, 在标准的 reST 中, 是没有特殊的标记可以实现上面的功能.

4.6. 交叉链接标记

为了在文档中实现任意章节的交叉引用, 在标准的 reST 中这样的标签有些 “不好” : 每个标签必须先于一个章节的标题; 每个标签的名字也必须在整篇文档中不同.

你可以使用 :ref:`label-name` 指向这些章节.

Example:

例如:

.. _my-reference-label:

Section to cross-reference
--------------------------

This is the text of the section.

It refers to the section itself, see :ref:`my-reference-label`.

此处的 :ref: 将被换成标题名.

当然, 你也可以指向任意的标签 (不止是章节的题目) 如果你提供链接的文字 :ref:`link text <reference-label>`.

4.7. 段落级别的标记

这些指令创建短的段落并可以像正常的段落一样被包含:

note

当使用任何的 API 时所需要注意的问题及信息. 指令的内容应该写完整并包含合适的标点.

例子:

.. note::

   This function is not suitable for sending spam e-mails.
warning

和上面所描述的一样, 给出一些警告. 在不引起用户恐慌的情况下使用, 给出某些可能如冲突, 数据丢失或安全问题.

versionadded

这个用于描述 Python 新版本引入的新特性, 如库或 C 的 API. 如果在一个完整的模块中使用, 请将此放到文档最前面.

第一个参数必须要给定, 并且是那个版本号; 你可以增加第二个参数, 用以包含一个简明的改变.

例如:

.. versionadded:: 3.1
   The *spam* parameter.

注意, 此处不能够有空行; 这是为了使得标记看起来连续.

versionchanged

versionadded 类似, 但是描述了什么时候和什么东西改变了. 比如新的参数, 更改的副作用等等.


impl-detail

这个用于标记 CPython 特定的信息. 参数可以是一个块或者只是一句.

CPython implementation detail: This describes some implementation detail.

More explanation.

或者:

.. impl-detail:: This shortly mentions an implementation detail.

CPython implementation detail:” is automatically prepended to the content.

CPython implementation detail:” 会自动的增加.

seealso

很多章节包含了一个列表, 放着一些参考的文档. 它们就被放在 seealso 中.

seealso 指示符一般防在一个章节到另一个字章节的前面. 在 HTML 输出时, 它会防在一个悬浮的框中.

seealso 中应该是一个 reST 的定义列表. 比如:

.. seealso::

   Module :mod:`zipfile`
      Documentation of the :mod:`zipfile` standard module.

   `GNU tar manual, Basic Tar Format <http://link>`_
      Documentation for tar archive files, including GNU tar extensions.
rubric

这个控制符创建一个段落头, 但是不会放到目录下. 这个经常用于脚注的标题.

centered

这个指示符用于创建一个居中黑体的段落. 像下面这样使用:

.. centered::

   Paragraph contents.

4.8. 目录标记

因为 reST 并没有将多个文档连在一起的能力, 或者是将文档拆分成多个输出文件, Sphinx 使用了自定义的指示符来讲多个文件联系起来, 就像一个目录一样. toctree 指示符是最主要的元素.

toctree

这个用于插入一个 “TOC tree” 在当前的位置, 使用独立的给定文件的 TOC (包括 “sub-TOC tree”) . 一个数字 maxdepth 选项可以用于指明其层数; 默认情况下会插入所有的.

考虑下面的例子(z摘自库函数索引):

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more files listed here)

这里完成了两件事情:

  • 从所有这些文件生成的目录将被插入进去, 并且其层数是 2 , 这意味只有一层嵌套的标题. 在这些文件中的 toctree 指示符也会被考虑进来.
  • Sphinx 知道这些文件相对的顺序, 并且它知道它们之间的关系. 从这里, 会生成像 “next chapter” , “previous chapter” 和 “parent chapter” 的链接.

在最后, 所有被包含的文件都会被包含; Sphinx 在没找到文件时将会发出一个警告, 因为这意味着这个文件无法导航.

在源目录的最顶层的特殊文件 contents.rst , 是整个层次的根; 在这里 “Contents” 页将被生成.

4.9. 索引标记

Sphinx 会自动生成索引, 从前面提及的所有的信息单元 (像函数, 类或属性) 产生.

但是, 也有一个显示的指令, 来产生更易理解的索引, 并且开关在文档中的某些条目.

这个指令是 index 并且包含多个索引条目. 每个条目包含一个类型和值, 以冒号分割.

举个例子:

.. index::
   single: execution; context
   module: __main__
   module: sys
   triple: module; search; path

这里包含了五个条目, 这将会转换到生成的索引中, 并且链接至真正出现的位置 (或者, 在离线情况下, 将是其相应的页码).

可能的类型有:

single
创建一个单独的索引项. 可以通用一个分号分割子项目 (这也用于下面描述的条目).
pair
pair: loop; statement 是一个快捷方式, 创建两个索引项, 叫做 loop; statementstatement; loop.
triple
同样, triple: module; search; path 是一个快捷方式, 创建三个索引项, module; search patch, search; path modulepath; module search.
module, keyword, operator, object, exception, statement, builtin
这些创建两个索引项. 举个例子, module: hashlib 将会创建 module; hashlibhashlib; module 两项.

对于之包含 “single” 的条目, 可以用下面的快捷方式:

.. index:: BNF, grammar, syntax, notation

这将创建四项索引项.

4.10. 语法显示

现在有个特殊的标记, 可以用以显示一个正规的语法. 这个标记很简单, 但是不尝试对所有 BNF (或继承的形式) 进行模仿, 但是提供足够的东西, 允许显示自由内容的语法, 以一种方式, 可以链接至定义的符号列表中. 有一个这样的指示符:

productionlist

这个指示符用于包括一组 production . 每个 production 都给定单独一行, 并包含一个名字, 以冒号分割, 接下来则是定义. 如果定义跨越多行, 每个续行必须以一个与上面的冒号对齐的形式给出.

productionlist 中空行是不允许的.

定义可以包含解释的文字, 像 unaryneg ::= "-" `integer`, 这样就会生成交叉引用.

注意此处的没有其他会被 reST 解析了. 所有像 *| 都不需要转义.

下面是一个例子:

.. productionlist::
   try_stmt: try1_stmt | try2_stmt
   try1_stmt: "try" ":" `suite`
            : ("except" [`expression` ["," `target`]] ":" `suite`)+
            : ["else" ":" `suite`]
            : ["finally" ":" `suite`]
   try2_stmt: "try" ":" `suite`
            : "finally" ":" `suite`

4.11. 替换

默认的定义下, 文档系统提供了三种替换. 它们可以在配置文件 conf.py 中设置.

|release|

替换成此文档对应的 Python 发行版本. 这是一个完整版本的字符串, 包括 alpha/beta/release candidate 标记, 比如 2.5.2.b3.

|version|

替换成对应的 Python 版本. 这只包含主要及次要的版本部分, 比如 2.5, 也包含了 2.5.1.

|today|

替换成当前的日期, 或者是在配置文件中设置的日期. 一般的格式为 April 14, 2007.

Footnotes

[1]有一个标准的 .. include 指示符, 但是如果找不到文件就会产生一个错误. 而此处的指示一些提示.