建造文档
==========================
你需要安装 Python 2.4 或更高版本; 用于建造该文档的工具包是用 Python 写的.
它叫做 *Sphinx*, 它不包含在 Python 树上, 而需要单独维护.
还需要 docutils, 它提供 Sphinx 使用的基本标记, Jinja,
它是一个模板引擎, 还有可选的 Pygments, 它是一个代码高亮器.
使用 make
----------
幸运的是, 已经准备了一个 Makefile, 以便在 Unix 上, 只要你安装了 Python
和 Subversion, 你就运行 ::
cd Doc
make html
来 check out :file:`tools/` 子目录下的必要工具,
以及建造 HTML 格式输出文件. 要查看生成的 HTML, 在运行 "make"
之后, 用你最爱的浏览器打开 :file:`build/html/index.html`.
(你可以使用 `FireFox `_
(`火狐 `_))
可用的 make targets 有:
* "html", 这将建造独立的 HTML 文件供离线阅读.
* 这将建造 HTML 文件以及一个 HTML Help 项目文件,
可以用它们编译成一个单独的 HTML (.chm) 文件 --
在 Microsoft Windows 下很流行, 在每个平台上都非常方便.
要创建 CHM 文件, 你需要用 Microsoft Help Workshop
打开生成的项目 (.hhp) 文件.
* "latex", 这将建造 LaTeX 源文件, 可以作为 "pdflatex" 的输入来产生 PDF
文档.
* "text", 这将为每个源文件生成一个纯文本文件.
* "linkcheck", 这将检查所有的外部引用是否坏了,
重定向了 或者 存在异常, 并且输出这些信息到
stdout 以及 一个纯文本 (.txt) 文件.
* 这将建造一个覆盖在当前版本下所有 版本增加/版本改变/失效 的条目.
这意味着这可以作为 "最近更新" 文档作者的一个帮手.
* 这将建造一个覆盖标准库模块和 C API 的概要.
* "pydoc-topics", 这将建造一个 Python 模块, 它包含一个为字典, 键为
:file:`tools/sphinxext/pyspecific.py` 中定义的标签,
内容是其纯文本文档 -- pydoc 需要这些来显示主题和关键自帮助.
"make update" 使用 Subversion 更新的 :file:`tools/` 中的文件.
没有 make
------------
你需要安装 Sphinx 包, 可以通过 svn co ::
svn co http://svn.python.org/projects/external/Sphinx-0.6.5/sphinx tools/sphinx
也可以从 PyPI 里安装它.
然后, 你需要安装 Docutils, 可以通过 svn co ::
svn co http://svn.python.org/projects/external/docutils-0.6/docutils tools/docutils
也可以从 http://docutils.sf.net/ 安装它.
你还需要 Jinja2, 可以通过 svn co ::
svn co http://svn.python.org/projects/external/Jinja-2.3.1/jinja2 tools/jinja2
也可以从 PyPI 里安装它.
你也可以安装 Pygments (可选), 可以通过 svn co ::
svn co http://svn.python.org/projects/external/Pygments-1.3.1/pygments tools/pygments
也可以从 http://pypi.python.org/pypi/Pygments 安装它.
Then, make an output directory, e.g. under `build/`, and run
然后, 指定一个输出文件夹, 如 `build/`, 并运行 ::
python tools/sphinx-build.py -b . build/
在这里 `` 为 html, text, latex, htmlhelp 中之一
(解释见上文的 make targets).