6. 建造文档

你需要安装 Python 2.4 或更高版本; 用于建造该文档的工具包是用 Python 写的. 它叫做 Sphinx, 它不包含在 Python 树上, 而需要单独维护. 还需要 docutils, 它提供 Sphinx 使用的基本标记, Jinja, 它是一个模板引擎, 还有可选的 Pygments, 它是一个代码高亮器.

6.1. 使用 make

幸运的是, 已经准备了一个 Makefile, 以便在 Unix 上, 只要你安装了 Python 和 Subversion, 你就运行

cd Doc
make html

来 check out tools/ 子目录下的必要工具, 以及建造 HTML 格式输出文件. 要查看生成的 HTML, 在运行 “make” 之后, 用你最爱的浏览器打开 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 模块, 它包含一个为字典, 键为

  tools/sphinxext/pyspecific.py 中定义的标签, 内容是其纯文本文档 – pydoc 需要这些来显示主题和关键自帮助.

“make update” 使用 Subversion 更新的 tools/ 中的文件.

6.2. 没有 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<builder> . build/<outputdirectory>

在这里 <builder> 为 html, text, latex, htmlhelp 中之一 (解释见上文的 make targets).