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

并回答这些问题。


Running a build
---------------

A build is started with the :program:`sphinx-build` script.  It is called
like this::

     $ sphinx-build -b latex sourcedir builddir

where *sourcedir* is the :term:`source directory`, and *builddir* is the
directory in which you want to place the built documentation (it must be an
existing directory).  The :option:`-b` option selects a builder; in this example
Sphinx will build LaTeX files.

The :program:`sphinx-build` script has several more options:

**-a**
   If given, always write all output files.  The default is to only write output
   files for new and changed source files.  (This may not apply to all
   builders.)

**-E**
   Don't use a saved :term:`environment` (the structure caching all
   cross-references), but rebuild it completely.  The default is to only read
   and parse source files that are new or have changed since the last run.

**-d** *path*
   Since Sphinx has to read and parse all source files before it can write an
   output file, the parsed source files are cached as "doctree pickles".
   Normally, these files are put in a directory called :file:`.doctrees` under
   the build directory; with this option you can select a different cache
   directory (the doctrees can be shared between all builders).

**-c** *path*
   Don't look for the :file:`conf.py` in the source directory, but use the given
   configuration directory instead.  Note that various other files and paths
   given by configuration values are expected to be relative to the
   configuration directory, so they will have to be present at this location
   too.

   .. versionadded:: 0.3

**-C**
   Don't look for a configuration file; only take options via the ``-D`` option.

   .. versionadded:: 0.5
   
**-D** *setting=value*
   Override a configuration value set in the :file:`conf.py` file.  (The value
   must be a string value.)

**-A** *name=value*
   Make the *name* assigned to *value* in the HTML templates.

**-N**
   Do not do colored output.  (On Windows, colored output is disabled in any
   case.)

**-q**
   Do not output anything on standard output, only write warnings and errors to
   standard error.

**-Q**
   Do not output anything on standard output, also suppress warnings.  Only
   errors are written to standard error.

**-P**
   (Useful for debugging only.)  Run the Python debugger, :mod:`pdb`, if an
   unhandled exception occurs while building.


You can also give one or more filenames on the command line after the source and
build directories.  Sphinx will then try to build only these output files (and
their dependencies).