Sphinx入门¶
这是Sphinx文档生成器的说明书,Sphinx是一个工具,它能够把一组 reStructuredText 格式的文件转换成各种输出格式,而且自动地生成交叉引用,生成目录等。也就是说,如果有一个目录,里面包含一堆reST格式的文档(可能子目录里面也同样存在reST格式的文档),Sphinx能够生成一个漂亮的组织结构以及便于浏览和导航的HTML 文件(这些文件在其他的文件夹中)。当然对于同样的来源文件(reST格式),它也能够生成一个能够被编译(生成)PDF版本的LaTeX格式的文件,或者直接使用 rst2pdf 生成PDF文件。
Sphinx注重的是人工的文档,而不是自动生成的API文档。尽管Sphinx或多或少地也支持自动生成的API文档,如果需要纯粹的API文档,可以看看 Epydoc (Epydoc也支持reST格式)。
Sphinx是一个工具,她能够轻易地创建智慧和优雅的文档,她是出自Georg Brandl之手,在BSD许可证下授权, Sphinx具有如下的特点:
- 输出格式: 超文本标记语言 (包括Windows HTML帮助),LaTeX (可打印的PDF版本),手册页,纯文本
- 丰富的交叉引用: 语义标记以及针对函数,类,引用,词汇表(术语)和相似的信息块的自动链接
- 层次结构: 简单的文本树定义,就能自动地链接到同层(兄弟姐妹)、上一层(父母)以及下一层(子女)的文本位置
- 自动生成目录: 通用索引以及语言模块的目录
- 代码高亮: 代码自动高亮,通过使用 Pygments
- 扩展功能: 自动测试的代码片段,包括从Python模块(API文档)的文档字符串
Sphinx 使用 reStructuredText 作为她的标记语言,她的优点大部分是来自于reStructuredText 以及reStructuredText 的解析和转换工具(套件) Docutils 的强大以及简单明了。
转换其他文件系统¶
她最初是为了新版的 python文档, 因此在python项目的文档具有完美的特性,但是同样支持c/c++,目前正在计划增加对其他的语言的支持。 理所当然,本页面也是使用Sphinx创造自reStructuredText格式源!
本节的目的是为给那些从其他文件系统迁移到reStructuredText/Sphinx上的人提供一些有用的提示。
- Gerard Flanagan写了一个从纯html格式到reST格式的脚本;这个脚本能在 Python Package Index 上被找到。
- 为了转换旧的Python文档到Sphinx,“转换器”在 the Python SVN repository 上。它包含了从python文档形式的LaTeX标记到Sphinx reST的代码。
- Marcin Wojdyr写了一个从Docbook到带有Sphinx标记的reST;它位于 Google Code。
- Christophe de Vienne 写了一个从Open/LibreOffice文件到Sphinx的转换工具: odt2sphinx。
- 为了转换不同的标记,Pandoc 是一个很有用的工具。
安装先决条件¶
- 对于Python 2,需要 Python 2.4 (或者以上版本)
- 对于Python 3,需要 Python 3.1 (或者以上版本)
- docutils_ (0.7或者SVN上的trunk版本) 和 Jinja2
- Pygments (如果需要代码高亮)
- uuid (如果使用 Python 2.4 )
绿色的箭头指定“详细信息”链接,这些链接指向了关于描述的功能的高级话题的章节。
设置文档来源¶
一个文档集合的根目录被称为 源目录。源目录 包含Sphinx配置文件 conf.py
,在配置文件里面可以配置Sphinx如何读取源文件以及如何生成文件等等各方面。 [1]
Sphinx提供了一个脚本 sphinx-quickstart,该脚本能够设置一个源目录以及通过几个简单的问答设置一个默认的配置文件 conf.py
。只需要运行:
$ sphinx-quickstart
接着回答问题。(务必选择"autodoc"扩展。)
Sphinx提供的"API documentation"生成器称为 sphinx-apidoc;更详细的内容参看 invocation-apidoc。
定义文档结构¶
假设你已经执行了 sphinx-quickstart。它创建了一个包含 conf.py
以及主文件 index.rst
(如果你接受了默认选项)的文件夹。master document 的主要作用是一个欢迎页面以及包含了树状内容表的“根”(或者 toctree)。
连接多个文件到单个层次结构的文件的方式是Sphinx增强了reStructuredText的主要事情之一。
toctree指令(标识符)最初是空的,看起来像这样:
.. toctree::
:maxdepth: 2
你可以添加文档列表在指令(标识符)中的*内容*位置:
.. toctree::
:maxdepth: 2
intro
tutorial
...
上面就是包含toctree的文件实际的样子。被包含的文档是以 文件名s 给出,简而言之,你可以脱离文件名扩展而直接使用斜线作为目录分隔符。
|more| 更详细的内容请见 toctree 指令(标识符)。
现在,您可以创建你列在toctree中的文件,并添加内容,章节的标题会被插入(至多到“最大深度”的层次)到toctree指令(标识符)标识的位置。当然,Sphinx知道你的文件的顺序以及层级结构。(他们可能会包含 toctree
指令(标识符)本身,这意味着你可以创建深层嵌套的层次结构,如果必要的话。)
添加内容¶
在Sphinx的源文件中,你可以使用标准reStructuredText的大部分功能。Sphinx也增加一些新的功能。例如,你可以通过使用可移植的方式(适应于所有的输出类型)-- ref
来实现跨文件间的引用。
举个例子,如果您正在查看的HTML版本,你可以看看这个文件的源代码 - 在侧边栏使用“显示源代码”的链接。
|more| 请参看 rst-primer 更加详细地学习reStructuredText,可以访问 sphinxmarkup 了解Sphinx增加的标记(标识符)列表。
运行构建¶
现在,你已经添加了一些文件和内容,让我们来做第一个文件构建。构建是由 sphinx-build 程序开始的,像如下调用:
$ sphinx-build -b html sourcedir builddir
上面提到的 sourcedir 是指 源目录,builddir 是指你想放置的生成文件的位置。-b
选择了生成器;在本例中Sphinx将会生成HTML格式的文件。
|more| invocation 中列出了 sphinx-build 所支持的选项。
因为 sphinx-quickstart 生成了 Makefile
和 make.bat
文件,这些文件能够减少不少工作:有了它们你就可以运行
$ make html
生成HTML文件在制定的目录。执行无参数的 make
可以看到哪些目标文件(makefile文件)可用。
怎样生成PDF文件?
make latexpdf
运行 LaTeX builder
,实际上是调用pdfTeX工具元件。
文档对象¶
注:在这里domain翻译成域,可以理解成不同的编程语言的集合对象,像python domain, java domain, C/C++ domain等。
Sphinx一个主要目标是在任何 域 中简单的 objects 文档(从非常笼统的意义上说)。域 是指一个集合对象类型属于一个整体,完整的标记来创建和引用这些对象的描述。
Python是最突出的域。如记录python的内建函数 enumerate()
,你只需要添加如下的内容到源文件中:
.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
会呈现出(在文档中会显示):
-
enumerate
(sequence[, start=0])¶ Return an iterator that yields tuples of an index and an item of the sequence. (And so on.)
指令(标识符)的参数就是描述对象的 说明(签名),内容是它的文档。允许多个说明(签名),单独成行(每个独立一行)。
Python是默认的域,所以不需要在域名前标记前缀:
.. function:: enumerate(sequence[, start=0])
...
做了同样的工作如果你保持默认的域以及它默认的设置。
Sphinx提供了许多其他的指令(标识符)为了标识python对象的其他的类型,例如:py:class
or py:method
。还设有一个为每个这些对象类型的交叉引用 角色。 下面的内容会创建一个到 enumerate()
文档的链接:
The :py:func:`enumerate` function can be used for ...
这就是结果: 链接到 enumerate()
.
再次提醒,如果使用默认域,py:
是可以不用添加的。不用关心真正包含 enumerate()
的文档的文件;Sphinx能够找到以及为它建立链接。
每个域对说明(签名)样式有着特点的规定,并格式化输出显得漂亮些,或者增加些特性如链接到参数类型,像在C/C++域。
|more| 请查看 domains 获取所有可用的域以及指令(标识符)/角色。
基本配置¶
前面我们提到了 conf.py
文件控制着Sphinx如何处理文档。该文件,作为Python源文件执行,你可以在文件中赋予的配置值。 对高级用户:因为文件是通过Sphinx执行,用户可以做一些不平凡的任务,像增加 sys.path
的值或者导入一个模块找出记录文档的版本。
你可能需要修改的配置值是已经通过 sphinx-quickstart 写入到 conf.py
中并且注释起来(使用标准python语法: #
在行的开头)。如果要定制配置值而不是使用 sphinx-quickstart 生成的值,只需要增加额外的赋值。
请记住,配置文件使用的是Python的字符串,数字,列表等语法。文件默认情况下是以UTF-8的格式保存,在文件的首行声明编码格式。如果需要使用non-ASCII格式,需要使用python的Unicode字符串*(像 project = u'Exposé'
)。
|more| 所有可用的配置值请参看 build-config 。
Autodoc¶
注:无法找到合适的词语来表示autodoc,直接用英文代替。
在记录python源代码的时候,通常需要在源文件,文档字符串中加入大量的记录(文字)。Sphinx支持直接使用python自身模块的文档字符创通过使用称为"autodoc"的 extension。(这个扩展是python的一个模块,为Sphinx项目提供额外的特性。)
为了能够使用autodoc,你需要通过在配置文件 conf.py
中加入字符串 'sphinx.ext.autodoc'
到 :confval:`extensions` 列表中来激活。接着,你就有一些额外的指令(标识符)可以任由支配了。
例如,为了记录函数 io.open()
,从源文件中读取它的说明(签名)以及文档字符串,你可以这些写:
.. autofunction:: io.open
当然你也能自动地记录整个类或者模块,使用自动的指令(标识符)的member选项,像:
.. automodule:: io
:members:
autodoc需要导入模块以便提取文档字符串。因此,必须在配置文件 conf.py
中添加模块所在的路径到 sys.path
。
|more| autodoc更多的特性请参考 sphinx.ext.autodoc
。