Python 高级编程（第2版）--第9章 文档化你的项目

文档化你的项目

• 7 项技术写作规则，是最佳实践的概述。
• reStructuredText 入门，它是在大多数 Python 项目中使用的纯文本标记语法。
• 建立良好的项目文档的编写指南。

7 项技术写作规则

编写良好的文档在许多方面比编写代码更容易。一个全面的文本，可以用来理解一个设计、一个 API 或任何构成的代码库。7 个规则：

• 两步写作：专注于想法，然后审查和塑造你的文本。
• 定位读者：谁会读？
• 使用简单的风格：保持直接和简单。使用好的语法。
• 限制信息范围：一次引入一个概念。
• 使用现实中的代码示例：应避免使用“Foos”和“bars”。
• 使用轻量且充分的方法：你不是在写一本书！
• 使用模板：帮助读者习惯。

两步写作

第一步删除文本的风格和组织，并专注于其内容。第二步包括回读整个文本并对其进行修正，以便每个人都能理解。修正文本意味着增强其风格，纠正其错误，重新组织它，并删除任何冗余的信息。

定位读者

好的文档应该遵循一个简单的规则——每个文本都只有一种类型的读者。个好的做法是提供一个简短的介绍性文本，在一个句子中解释文档是什么，并指导读者去读适当的部分。Atomisator 是一个产品，它提取 RSS 源并将其保存在数据库中，并带有筛选功能。

• 如果你是开发人员，你可能需要查看API描述（api.txt）。
• 如果你是管理人员，你可以阅读功能列表和常见问题（features.txt）。
• 如果你是一个架构师，你可以阅读架构和基础设施的说明（arch.txt）。
• 通过这种方式考虑你的读者，你才可能输出更好的文档。

使用简单的风格

保持句子短而简单，请记住几个提示。

• 使用简单的句子。它们不应超过两行。
• 每一段最多应由 3 或 4 个句子组成，表达一个主要思想。让你的文本互相呼应。
• 不要重复太多。避免新闻风格，其中的想法一再重复，以确保他们的理解。
• 不要使用几种时态。大多数时候，现在时态是足够的。
• 如果你不是一个真正优秀的作家，不要在文本中讲笑话。在技术文本中滑稽是很难的，很少有作家掌握它。

限制信息范围

不好的软件文档有个简单的迹象——你正在寻找一些你知道存在于某处但你找不到的信息。为了避免这种影响，段落应该被聚集在给定章节的有意义的标题下，全局文档标题应该用短语来组织内容。

使用现实中的代码示例

Foo 和 bar 是坏成员。当读者试图通过一个使用示例来理解一段代码如何运行时，不切实际的示例会让代码难以理解。通常的做法是确保每个代码示例都可以剪切并粘贴到一个真正的程序中。代码示例应该可直接在实际程序中复用。

使用轻量且充分的方法

在大多数敏捷方法中，文档不是首要的。相比细节文档，使软件正常工作是最重要的事情。一个好的做法是定义真正的文档需求，而不是创建一个详尽的文档集。

使用模板

使用模板强制文档的通用模式，可以使人们更有效地使用它们。他们习惯了结构，知道如何快速阅读它。为每种文档提供模板还为作者提供了一个快速开始的脚手架。

reStructuredText 入门

reStructuredText 也被称为 reST。它是一种在 Python 社区中广泛用于文档化软件包的纯文本标记语言。reST 包含在 docutils 中，这个包提供了一套脚本来将 reST 文件转换为各种格式，如 HTML, LaTeX, XML 或甚至 S5。

开始编写 reST 文档需要知道的最小元素集合如下。

• 章节结构（Section structure）。
• 列表（Lists）。
• 行内标记（Inline markup）。
• 文字块（Literal block）。
• 链接（Links）。

章节结构

文档的标题及其部分使用非字母数字的字符下划线。它们可以是上划线和下划线，并且通常的做法是，在标题中使用这种双标记，在章节中使用一个简单的下划线。

最常用的字符下划线的标题是以下列顺序进行排序：=、- 、_、:、#、+、^。

当一个字符用于章节时，它与其级别相关联，并且必须在整个文档中始终使用。

列表

reST 提供了易读的自动枚举特性的列表语法，主要有：无序列表，枚举列表和自定义列表。

行内标记

文本可以使用行内标记来设置样式。

• *强调*：斜体。
• **加粗强调**：粗体。
• ‘’行内预格式化’’：行内预格式化文本（通常为等宽，终端样式）。
• ’带有链接的文本’_：只要文档中提供了超链接，这将被替换为超链接。

文字块

两个冒号用于标记代码块，代码块需要进行缩进。不要忘记在 :: 和代码块之后添加一个空行，否则不会被渲染。请注意，冒号字符可以放在文本行中。在这种情况下，它将被渲染为单个冒号。如果不想保留单个冒号，可以在前面的文本和 :: 之间插入一个空格。在这种情况下，:: 将被解释并且完全删除。

链接

只要在当前文档中提供了链接，就可以通过以两个点开头的特殊行将文本更改外部链接。通常的做法是将外部链接分组放到文档的末尾。当要链接的文本包含空格时，它必须用’（反引号）字符包围。也可以通过在文本中添加标记来使用内部链接。

构建文档

指导读者和作者的一个更简单的方法是向每个人提供帮助和指导。

从作者的角度来看，这可以通过一组可重用的模板以及描述如何以及何时在项目中使用它们的指南来完成。它被称为文档集（documentation portfolio）。

从读者的角度来看，重要的是能够无痛地浏览文档，并习惯于有效地查找信息。它是通过构建文档格局（documentlandscape）来完成的。

软件项目可以有许多种类的文档，从直接引用代码的底层文档，到提供应用程序的高层次视图的设计文档。

软件项目中的一组常见文档可以分为 3 类。

• 设计：包括提供架构信息和底层设计信息的所有文档，例如类图或数据库图。
• 用法：包括有关如何使用软件的所有文档；可以是以一本手册和教程或模块级帮助的形式。- 操作：这提供了有关如何部署，升级或操作软件的指南。

设计

创建此类文档的重点是确保目标读者是完全知道的，内容范围有限的。因此，为作者提供一点建议就是设计文档的通用模板尽量保持轻量级的结构。

这样的结构可能包括：

• 标题；
• 作者；
• 标签（关键字）；
• 说明（摘要）；
• 目标（谁应该读这篇文章？）；
• 内容（带图）；
• 参考的其他文件。

使用

使用文档描述软件的特定部分是如何使用的。本文档可以描述底层部分，如函数的工作原理，也可以描述高层部分，如调用程序的命令行参数。这是框架应用程序中的文档的最重要的部分，因为目标读者主要是将要重用代码的开发人员。

3 种主要的文件如下。

• 技巧：这是一个简短的文档，解释如何做某事。这种文件瞄准一个读者，并专注于一个特定的主题。
• 教程：这是一个逐步的文档，说明如何使用软件的功能。本文档可以引用配方文档，每个实例仅供一个读者使用。
• 模块助手：这是一个底层文档，用于说明模块包含的内容。当你通过模块调用内置的帮助时，可以显示此文档。

技巧

一个技巧（recipe）文档解答一个非常具体的问题，并提供一个解决方案来解决问题。与单个区域/项目相关的这样一组配方通常被称为攻略（cookbook）。

这些技巧必须简短，并且结构如下。

• 标题。
• 提交者。
• 最近更新时间。
• 版本。
• 类别。
• 说明。
• 源（源代码）。
• 讨论（解释代码的文字）。
• 评论（来自网络）。

通常，它们很长，超出一屏，但是却没有深入细节。这种结构完全符合软件的需要，可以在通用结构中再进行调整，向其中添加目标读者，并且用标签替换类别：

• 标题（短句）。
• 作者。
• 标签（关键字）。
• 谁应该读这个？
• 先决条件（例如要读取的其他文档）。
• 问题（简短说明）。
• 解决方案（主文本，一个或两个屏幕）。
• 参考文献（指向其他文档的链接）。

上面没有日期和版本，因为像管理项目中的源代码一样管理项目文档。这意味着处理文档的最好方法是通过版本控制系统进行管理。在大多数情况下，这与用于项目代码的代码仓库完全相同。

教程

教程和配方相比有着不同的目的。它不打算解决孤立的问题，而是描述如何逐步使用应用程序的功能。这可能比配方更长，并且可能涉及应用程序的许多部分。

这种文件的结构如下所示。

• 标题（短句）。
• 作者。
• 标签（文字）。
• 说明（摘要）。
• 谁应该读这个？
• 先决条件（例如要读取的其他文档）。
• 教程（正文）。
• 参考文献（指向其他文档的链接）。

模块助手

模块助手模板是可以添加到我们的集合中的最后一个模板。模块助手指的是一个单独的模块，它主要提供内容的描述以及使用示例。

一些工具可以通过使用 pydoc 提取 docstrings 和计算模块助手来自动构建这样的文档，例如 Epydoc。因此，可以基于内省 API 生成大量的文档。通常在 Python 框架中会提供这种文档。

这种方法的主要问题如下。

• 无法智能的选择感兴趣的模块生成文档。
• 代码可能会被文档混淆。

此外，模块文档提供的例子有时可能涉及模块的多个部分，并且它们很难在函数和类的 docstrings 之间进行拆分。模块的 docstring 的目的是可以在模块的顶部写入文本。

另一种方法是将这些文本拆分到单独的文件中。然后通过手动的操作决定哪个 Python 模块具有模块助手文件。

模块助手的模板非常简单，因为它在内容写入之前只包含一些元数据。

• 标题（模块名称）。
• 作者。
• 标签（文字）。
• 内容。

操作

操作文档用于描述如何操作软件，需要考虑以下几点。

• 安装和部署文档。
• 管理文件。
• 常见问题（FAQ）文档。
• 解释人们如何贡献，请求帮助或提供反馈的文档。

构建自己的文档集

随着时间的推移，你最终将开发自己的模板和风格来制作文档。但始终记住让项目文档保持轻量且充分的方法：每个添加的文档应该有一个明确定义的目标读者，并应填补真正的需要。不增添实际价值的文档不应写入。

真正推荐明确作者的情况是各种设计文档，特别是在设计过程严格正式化的项目中。最好的例子就是关于 Python 语言增强提案的一系列 PEP 文档。

构建格局

需要提供一种方法来对其进行分组和整理，以构建读者将拥有的文档。这就是 Andreas Rüping 所说的文档格局，指的是读者在浏览文档时使用的思维导图。他得出的结论是，组织文件最好的方法就是建立一个逻辑树。即：由不同类型的文档组成的文档集需要存放在一个树形的目录结构中。

览文档时，每个级别的索引页面很有用处，可以帮助作者和读者。构建文档格局有两个步骤。

• 为生产者（作家）建立一树形布局。
• 在生产者树形布局的顶部为消费者（读者）构建树形布局。

生产者的布局

从生产者的角度来看，每个文档都像 Python 模块一样被处理。它应该存储在版本控制系统中，并像代码一样工作。存储在文件夹树中的 reStructuredText 文件与软件代码一起在版本控制系统中可用，并且是为生产者构建文档景观的方便的解决方案。

消费者的布局

从消费者的角度来看，重要的是制定索引文件，并以易于阅读和看起来不错的格式呈现整个文档。网页是最好的选择，并且容易从 reStructuredText 文件中生成。

Sphinx（http://sphinx.pocoo.org）是一组脚本和 docutils 的扩展，可用于从我们的文本树中生成 HTML 结构。此工具用于（例如）构建 Python 文档，并且许多项目现在将其用于其文档。可以使用 pip 轻松地安装 Sphinx 包。

Sphinx 提供了一些 docutils 扩展来驱动这些功能，主要有以下几个步骤。

• 构建目录的指令。
• 将文档注册为模块助手的标记。
• 在索引中添加元素的标记。

文档构建与持续集成

消费者的角度看，Sphinx 真的提高了文档的可读性和用户体验。如前所述，当一部分以 dosctrings 或模块助手的形式的文档与代码紧密耦合时，文档就显得特别有用。虽然这种方法确保文档的源版本与其文档中的代码相匹配，但并不能保证文档读者能够访问最新的编译版本。

托管使用 Sphinx 构建的文档的最佳方式是生成 HTML 构建，并将其作为你选择的 Web 服务器的静态资源。Sphinx 提供了合适的 Makefile 使用 make html 命令来构建 HTML 文件。