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).