Sphinx

简介
============

:译者: CliffPeng

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

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


从其它系统转换
-----------------------------

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

* Gerard Flanagan 写了一段脚本将纯 HTML 转换为 reST ；可在
  `Launchpad <http://bazaar.launchpad.net/~grflanagan/python-rattlebag/trunk/an
  notate/head:/src/html2rest.py>`_ 找到相关脚本。


* 要将旧的 Python 文档转换为 Sphinx，可以从 `Python SVN 仓库 <http://svn.python
  .org/projects/doctools/converter>`_ 找到相关转换工具。它包  括将 Python 文档风格
  标记转换为 Sphinx reST 的通用代码。

先决条件
-------------

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

.. _reStructuredText: http://docutils.sf.net/rst.html
.. _Pygments: http://pygments.org


建立文档源
------------------------------------

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

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

   $ sphinx-quickstart

并回答这些问题。


进行编译
---------------

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

     $ sphinx-build -b latex sourcedir builddir

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

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

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

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

**-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 将只试图
编译这些输出文件（及其附属文件）。