简介

原文地址: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 将只试图 编译这些输出文件(及其附属文件)。

SphinxIntroduction (last edited 2009-12-25 07:18:33 by localhost)