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

我们之前讨论的模板只是一个可以用来文档化软件的基础。随着时间的推移你最终将开发自己的模板和风格来制作文档。但始终记住让项目文档保持轻量且充分的方法每个添加的文档应该有一个明确定义的目标读者并应填补真正的需要。不增添实际价值的文档不应写入。每个项目都是独一无二的有不同的文档需求。例如具有简单用法的小型终端工具只要有一个 README 文件作为其文档格局就绝对足够了。如果目标读者被精确地定义并且一致的分组例如系统管理员则具有这样的最小单文档是完全正确的。此外不要太严格地应用提供的模板。示例提供的一些其他的元数据在大项目或严格规范化的团队中非常有用。例如标签旨在改进大文档中的文本搜索但由少量文档组成的文档格局中它不会提供任何有价值的信息。此外包括文档作者并不总是一个好主意。这种方法在开源项目中可能尤其值得怀疑。在这样的项目中你希望社区也贡献文档。在大多数情况下无论何时有需要这些文件都会不断更新。人们倾向于将文档作者也视为文档所有者。如果每个文档的作者总是指定的这可能会阻止人们更新文档。通常与明确提供的元数据注释相比版本控制软件可以提供关于真实文档作者的更清楚和更透明的信息。真正推荐明确作者的情况是各种设计文档特别是在设计过程严格正式化的项目中。最好的例子就是关于 Python 语言增强提案的一系列 PEP 文档。构建格局上一节中创建的文档集提供了文档级别的结构但是没有提供一种方法来对其进行分组和整理以构建读者将拥有的文档。这就是 Andreas Rüping 所说的文档格局指的是读者在浏览文档时使用的思维导图。他得出的结论是组织文件最好的方法就是建立一个逻辑树。换句话说由不同类型的文档组成的文档集需要存放在一个树形的目录结构中。这个地方对于作者在创建文档时以及在读者查找时都必须是显而易见的。浏览文档时每个级别的索引页面很有用处可以帮助作者和读者。构建文档格局有两个步骤。● 为生产者作家建立一树形布局。● 在生产者树形布局的顶部为消费者读者构建树形布局。生产者和消费者之间的这种区分是重要的因为他们在不同的地方并且以不同的格式访问文档。生产者的布局从生产者的角度来看每个文档都像 Python 模块一样被处理。它应该存储在版本控制系统中并像代码一样工作。作家不关心他们的散文的最后的外观它在哪里可用他们只是想确保他们正在写一个文档所以它是主题所涵盖的真正的事实的唯一来源。存储在文件夹树中的 reStructuredText 文件与软件代码一起在版本控制系统中可用并且是为生产者构建文档景观的方便的解决方案。按照惯例docs 文件夹用作文档树的根$ cd my-project$ find docsdocsdocs/sourcedocs/source/designdocs/source/operationsdocs/source/usagedocs/source/usage/cookbookdocs/source/usage/modulesdocs/source/usage/tutorial请注意树位于源码文件夹中因为 docs 文件夹将用作根文件夹用以在下一部分中设置特殊的工具。从那里可以在每个级别除根之外添加 index.txt 文件它用以说明文件夹包含什么类型的文档或总结每个子文件夹包含什么文档。这些索引文件可以定义它们包含的文档的列表。例如操作文件夹可以包含以下可用的操作文档的列表OperationsThis section contains operations documents:− How to install and run the project− How to install and manage a database for the project重要的是要知道人们往往忘记更新这些文件的列表以及表格的内容。所以最好让它们自动更新。在下一小节中我们将讨论一个工具在许多其他功能中也可以处理这种情况。消费者的布局从消费者的角度来看重要的是制定索引文件并以易于阅读和看起来不错的格式呈现整个文档。网页是最好的选择并且容易从 reStructuredText 文件中生成。Sphinxhttp://sphinx.pocoo.org是一组脚本和 docutils 的扩展可用于从我们的文本树中生成 HTML 结构。此工具用于例如构建 Python 文档并且许多项目现在将其用于其文档。在其内置的功能中它产生一个非常好的浏览系统以及一个轻量并且够用的客户端 JavaScript 搜索引擎。它还使用 pygments 来渲染代码示例这会输出非常好的语法高亮效果。Sphinx 可以很容易地配置为前面定义的文档格局。同时可以使用 pip 轻松地安装Sphinx 包。开始使用 Sphinx 的最简单的方法是使用 sphinx-quickstart 脚本。这个实用程序将通过 Makefile 生成一个脚本可以用来在每次需要时生成 Web 文档。它会交互地询问一些问题然后引导初始化整个文档源代码树和配置文件。一旦完成只要你想要你都可以很容易地调整它。让我们假设我们已经引导了整个 Sphinx 环境我们希望看到它的HTML 表示。这可以使用 make html 命令轻松完成如下所示project/docs$ make htmlsphinx-build -b html -d _build/doctrees . _build/htmlRunning Sphinx v1.3.6making output directory…loading pickled environment… not yet createdbuilding [mo]: targets for 0 po files that are out of datebuilding [html]: targets for 1 source files that are out of dateupdating environment: 1 added, 0 changed, 0 removedreading sources… [100%] indexlooking for now-outdated files… none foundpickling environment… donechecking consistency… donepreparing documents… donewriting output… [100%] indexgenerating indices… genindexwriting additional pages… searchcopying static files… donecopying extra files… donedumping search index in English (code: en) … donedumping object inventory… donebuild succeeded.Build finished. The HTML pages are in _build/html.除了 HTML 版本的文档之外该工具还能构建自动的页面例如模块列表和索引。Sphinx 提供了一些 docutils 扩展来驱动这些功能主要有以下几个步骤。● 构建目录的指令。● 将文档注册为模块助手的标记。● 在索引中添加元素的标记。在索引页上工作Sphinx 提供了一个 toctree 指令可以用来在文档中插入一个目录其中包含指向其他文档的链接。每行必须是具有相对路径的文件从当前文档开始。全局风格的名称可以通过与表达式匹配添加多个文件。例如我们以前在生产者环境中定义的 cookbook 文件夹中的索引文件可能如下所示CookbookWelcome to the Cookbook.Available recipes:… toctree:::glob:*使用此语法HTML 页面将显示 cookbook 文件夹中可用的所有 reStructuredText 文档的列表。这个指令可以在所有的索引文件中使用以构建一个可浏览的文档。注册模块助手对于模块助手可以添加一个标记以便在模块的索引页中自动列出如下所示session… module:: db.sessionThe module session…请注意此处的 db 前缀可用于避免模块冲突。Sphinx 将使用它作为一个模块类别并将所有以 db.开头的模块以这个类别进行分组。添加索引标记另一个选项可用于将文档链接到的条目填充到索引页如下所示session… module:: db.session… index::Database AccessSessionThe module session…这将会在索引页中添加两个新条目即 Database Access 和 Session。交叉引用最后Sphinx 提供了一个行内标记来设置交叉引用。例如到模块的链接可以这样做:mod:db.session这里:mod:是模块标记的前缀db.session是要链接到的模块的名称如先前注册的请记住:mod:以及前面的元素是由 Sphinx 在 reSTructuredText 中引入的具体指令。