Python 高手编程系列三千三百七十八：构建自己的文档集

我们之前讨论的模板只是一个可以用来文档化软件的基础。随着时间的推移，你最终将开
发自己的模板和风格来制作文档。但始终记住让项目文档保持轻量且充分的方法：每个添加的文
档应该有一个明确定义的目标读者，并应填补真正的需要。不增添实际价值的文档不应写入。
每个项目都是独一无二的，有不同的文档需求。例如，具有简单用法的小型终端工具
只要有一个 README 文件作为其文档格局就绝对足够了。如果目标读者被精确地定义并且
一致的分组（例如，系统管理员），则具有这样的最小单文档是完全正确的。
此外，不要太严格地应用提供的模板。示例提供的一些其他的元数据在大项目或严格
规范化的团队中非常有用。例如，标签旨在改进大文档中的文本搜索，但由少量文档组成
的文档格局中，它不会提供任何有价值的信息。
此外，包括文档作者并不总是一个好主意。这种方法在开源项目中可能尤其值得怀疑。在
这样的项目中，你希望社区也贡献文档。在大多数情况下，无论何时有需要，这些文件都会不
断更新。人们倾向于将文档作者也视为文档所有者。如果每个文档的作者总是指定的，这可能
会阻止人们更新文档。通常，与明确提供的元数据注释相比，版本控制软件可以提供关于真实
文档作者的更清楚和更透明的信息。真正推荐明确作者的情况是各种设计文档，特别是在设计
过程严格正式化的项目中。最好的例子就是关于 Python 语言增强提案的一系列 PEP 文档。
构建格局
上一节中创建的文档集提供了文档级别的结构，但是没有提供一种方法来对其进行分组和整理，以构建读者将拥有的文档。这就是 Andreas Rüping 所说的文档格局，指的是读
者在浏览文档时使用的思维导图。他得出的结论是，组织文件最好的方法就是建立一个逻
辑树。
换句话说，由不同类型的文档组成的文档集需要存放在一个树形的目录结构中。这个
地方对于作者在创建文档时以及在读者查找时都必须是显而易见的。
浏览文档时，每个级别的索引页面很有用处，可以帮助作者和读者。
构建文档格局有两个步骤。
● 为生产者（作家）建立一树形布局。
● 在生产者树形布局的顶部为消费者（读者）构建树形布局。
生产者和消费者之间的这种区分是重要的，因为他们在不同的地方并且以不同的格式
访问文档。
生产者的布局
从生产者的角度来看，每个文档都像 Python 模块一样被处理。它应该存储在版本控制
系统中，并像代码一样工作。作家不关心他们的散文的最后的外观，它在哪里可用，他们
只是想确保他们正在写一个文档，所以它是主题所涵盖的真正的事实的唯一来源。存储在
文件夹树中的 reStructuredText 文件与软件代码一起在版本控制系统中可用，并且是为生产
者构建文档景观的方便的解决方案。
按照惯例，docs 文件夹用作文档树的根：
$ cd my-project
$ find docs
docs
docs/source
docs/source/design
docs/source/operations
docs/source/usage
docs/source/usage/cookbook
docs/source/usage/modules
docs/source/usage/tutorial
请注意，树位于源码文件夹中，因为 docs 文件夹将用作根文件夹，用以在下一部分
中设置特殊的工具。
从那里，可以在每个级别（除根之外）添加 index.txt 文件，它用以说明文件夹包
含什么类型的文档或总结每个子文件夹包含什么文档。这些索引文件可以定义它们包含的
文档的列表。例如，操作文件夹可以包含以下可用的操作文档的列表：

Operations

This section contains operations documents:
− How to install and run the project
− How to install and manage a database for the project
重要的是要知道，人们往往忘记更新这些文件的列表以及表格的内容。所以最好让它们自
动更新。在下一小节中，我们将讨论一个工具，在许多其他功能中，也可以处理这种情况。
消费者的布局
从消费者的角度来看，重要的是制定索引文件，并以易于阅读和看起来不错的格式呈
现整个文档。网页是最好的选择，并且容易从 reStructuredText 文件中生成。
Sphinx（http://sphinx.pocoo.org）是一组脚本和 docutils 的扩展，可用于从我们的文
本树中生成 HTML 结构。此工具用于（例如）构建 Python 文档，并且许多项目现在将其
用于其文档。在其内置的功能中，它产生一个非常好的浏览系统，以及一个轻量并且够用
的客户端 JavaScript 搜索引擎。它还使用 pygments 来渲染代码示例，这会输出非常好的
语法高亮效果。
Sphinx 可以很容易地配置为前面定义的文档格局。同时，可以使用 pip 轻松地安装
Sphinx 包。
开始使用 Sphinx 的最简单的方法是使用 sphinx-quickstart 脚本。这个实用程序
将通过 Makefile 生成一个脚本，可以用来在每次需要时生成 Web 文档。它会交互地询问
一些问题，然后引导初始化整个文档源代码树和配置文件。一旦完成，只要你想要，你都
可以很容易地调整它。让我们假设我们已经引导了整个 Sphinx 环境，我们希望看到它的
HTML 表示。这可以使用 make html 命令轻松完成，如下所示：
project/docs$ make html
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.6
making output directory…
loading pickled environment… not yet created
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 1 source files that are out of date
updating environment: 1 added, 0 changed, 0 removed
reading sources… [100%] index
looking for now-outdated files… none found
pickling environment… done
checking consistency… done
preparing documents… done
writing output… [100%] index
generating indices… genindex
writing additional pages… search
copying static files… done
copying extra files… done
dumping search index in English (code: en) … done
dumping object inventory… done
build succeeded.
Build finished. The HTML pages are in _build/html.
除了 HTML 版本的文档之外，该工具还能构建自动的页面，例如模块列表和索引。
Sphinx 提供了一些 docutils 扩展来驱动这些功能主要有以下几个
步骤。
● 构建目录的指令。
● 将文档注册为模块助手的标记。
● 在索引中添加元素的标记。
在索引页上工作
Sphinx 提供了一个 toctree 指令，可以用来在文档中插入一个目录，其中包含指向
其他文档的链接。每行必须是具有相对路径的文件，从当前文档开始。全局风格的名称可
以通过与表达式匹配添加多个文件。
例如，我们以前在生产者环境中定义的 cookbook 文件夹中的索引文件可能如下所示：

Cookbook

Welcome to the Cookbook.
Available recipes:
… toctree::
:glob:
*
使用此语法，HTML 页面将显示 cookbook 文件夹中可用的所有 reStructuredText 文档
的列表。这个指令可以在所有的索引文件中使用，以构建一个可浏览的文档。
注册模块助手
对于模块助手，可以添加一个标记，以便在模块的索引页中自动列出，如下所示：

session

… module:: db.session
The module session…
请注意，此处的 db 前缀可用于避免模块冲突。Sphinx 将使用它作为一个模块类别，并
将所有以 db.开头的模块以这个类别进行分组。
添加索引标记
另一个选项可用于将文档链接到的条目填充到索引页，如下所示：

session

… module:: db.session
… index::
Database Access
Session
The module session…
这将会在索引页中添加两个新条目，即 Database Access 和 Session。
交叉引用
最后，Sphinx 提供了一个行内标记来设置交叉引用。例如，到模块的链接可以这样做：
:mod:db.session
这里，:mod:是模块标记的前缀，db.session是要链接到的模块的名称（如先前注册
的）；请记住:mod:以及前面的元素是由 Sphinx 在 reSTructuredText 中引入的具体指令。