|
Size: 5071
Comment:
|
Size: 4874
Comment:
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 71: | Line 71: |
| 脚本* sphinx-build *还有几个选项： | 脚本 *sphinx-build* 还有几个选项： |
| Line 78: | Line 78: |
| 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. |
不使用已保存的 `环境 <ShpinxEnvironment>`_ （该数据结构缓存所有的交叉引用）， 而是完全重新编译。缺省情况下将只对新的源文件或者上次编译之后已经修改过的源 文件进行读取和解析。 |
| Line 83: | Line 83: |
| 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). |
由于 Sphinx 在输出文件之前必须读取和分析所有的源文件，已经解析的源文件被缓存 为 "doctree pickles"。通常，这些文件被放置在编译目录下的 *doctrees* 目录中，设定 该选项后，你可以另外选择一个目录（doctrees 可以在所有的编译之间共享）。 |
| Line 90: | Line 88: |
| 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 |
不在源目录中查找 *conf.py* ` ，而使用给定的配置目录。注意，配置内容的许多不同的 其他文件和路径和配置目录相对的，因此它们也必须放置在该位置。（自0.3版开始增加） |
| Line 99: | Line 92: |
| Don't look for a configuration file; only take options via the ``-D`` option. .. versionadded:: 0.5 |
不查找配置文件，只使用 ``-D`` 选项设定的配置。（自0.5版开始增加） |
| Line 104: | Line 95: |
| Override a configuration value set in the :file:`conf.py` file. (The value must be a string value.) |
覆盖 *conf.py* 文件中所设定的配置值。（值必须是字符串值。） |
| Line 108: | Line 98: |
| Make the *name* assigned to *value* in the HTML templates. | 使 *name* 等于 HTML 模板中的 *value* 。 |
| Line 111: | Line 101: |
| Do not do colored output. (On Windows, colored output is disabled in any case.) |
不进行彩色输出（在 Windows 平台上，任何时候都不会使用彩色输出）。 |
| Line 115: | Line 104: |
| Do not output anything on standard output, only write warnings and errors to standard error. |
在标准输出设备上不作任何输出，只对普通错误输出警告和错误。 |
| Line 119: | Line 107: |
| Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. |
在标准输出设备上不作任何输出，同时也禁止警告。只对普通错误输出错误。 |
| Line 123: | Line 110: |
| (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. |
（仅对调试有用）如果在编译时出现未处理例外，运行 Python 调试器—— *pdb* 。 |
| Line 127: | Line 113: |
| 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). |
在命令行中，你可在源目录和编译目录之后给定一个或多个文件名。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 将只试图
编译这些输出文件（及其附属文件）。