Sphinx|简介

简介

原文地址:	http://sphinx.pocoo.org/intro.html
翻译人员:	CliffPeng
翻译日期:	2009年01月30日

本文档介绍的是文档编制软件 Sphinx 。该工具可以将一系列 reStructuredText 源 文本转换成各种不同的输出格式，并自动制作交叉引用（cross-references)、索引 等。也就是说，如果某目录中有一系列的 reST 格式文档（可能子目录中也有）， Sphinx 可以制作一份组织得非常完美的 HTML 文件（在其它目录中），便于浏览 和查找。但是从同一组源文件，它也可以制作一份 LaTex 文件，以便你将其转换为 PDF 格式的文档。

重点是针对手写文档，而不是自动生成的 API 文档。尽管对自动生成的文档也提供 了有限的支持（目的是为了与手写文档自由混合），但如果你需要纯 API 文档，可 以试下 Epydoc ，它也能够支持 reST 。

从其它系统转换

本节对那些想将其他文档系统转换为 reStructuredText 或 Sphinx 的人提供了一些 有用的提示。

• Gerard Flanagan 写了一段脚本将纯 HTML 转换为 reST ；可在 Launchpad 找到相关脚本。
• 要将旧的 Python 文档转换为 Sphinx，可以从 Python SVN 仓库 找到相关转换工具。它包 括将 Python 文档风格 标记转换为 Sphinx reST 的通用代码。

先决条件

Sphinx 需要 Python 2.4 以上才能运行。如果你喜欢源代码高亮显示支持，你还必须 安装 Pygments 类库――你可以通过安装工具 easy_install 。Sphinx 需要0.4版本的 docutils 或它的一些（可运行的） SVN 快速版本。

建立文档源

文档集合的根目录被称为 源目录 。通常，该目录中包含了 Sphinx 配置文件 conf.py ，但该 文件也可以存放在其他目录中，或称为 配置目录 （该功能自0.3版起支持）。

Sphinx 带有一段称作 sphinx-quickstart 的脚本，它可以设置 源目录 并通过问你一些问题创建 缺省的 conf.py 。只需运行:

$ sphinx-quickstart

并回答这些问题。

进行编译

编译工作由 sphinx-build 脚本启动。它的调用方式如下:

$ sphinx-build -b latex sourcedir builddir

其中 sourcedir 为 源目录 ，而 builddir 为要存放 已编译文档的目录（必须是已经存在的目录）。选项 -b 选择编译器，本例中 Sphinx 将编译 LaTex 文件。

脚本 sphinx-build 还有几个选项：

-a

如果设定该选项，将总是输出所有的文件。缺省情况下将只对已修改的源文件 进行输入。（这一点并不对所有编译器适用。）

-E

不使用已保存的 环境 （该数据结构缓存所有的交叉引用）， 而是完全重新编译。缺省情况下将只对新的源文件或者上次编译之后已经修改过的源 文件进行读取和解析。

-d path

由于 Sphinx 在输出文件之前必须读取和分析所有的源文件，已经解析的源文件被缓存 为 "doctree pickles"。通常，这些文件被放置在编译目录下的 doctrees 目录中，设定 该选项后，你可以另外选择一个目录（doctrees 可以在所有的编译之间共享）。

-c path

不在源目录中查找 conf.py ` ，而使用给定的配置目录。注意，配置内容的许多不同的 其他文件和路径和配置目录相对的，因此它们也必须放置在该位置。（自0.3版开始增加）

-C

不查找配置文件，只使用 -D 选项设定的配置。（自0.5版开始增加）

-D setting=value

覆盖 conf.py 文件中所设定的配置值。（值必须是字符串值。）

-A name=value

使 name 等于 HTML 模板中的 value 。

-N

不进行彩色输出（在 Windows 平台上，任何时候都不会使用彩色输出）。

-q

在标准输出设备上不作任何输出，只对普通错误输出警告和错误。

-Q

在标准输出设备上不作任何输出，同时也禁止警告。只对普通错误输出错误。

-P

（仅对调试有用）如果在编译时出现未处理例外，运行 Python 调试器―― pdb 。

在命令行中，你可在源目录和编译目录之后给定一个或多个文件名。Sphinx 将只试图 编译这些输出文件（及其附属文件）。