Question

项目文档的内容分为许多种。虽然我们不必在一开始就把所有文档都写出来，然而一旦缺少关键文档，就很可能造成项目止步不前。

《敏捷建模：极限编程和统一过程的有效实践》1 （Scott Ambler 著）一书是这样回答“应该何时写文档”这个问题的。

1 原书名为 Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process ，Scott W. Ambler / Ron Jeffries 著，张嘉路译，机械工业出版社，2003 年 1 月出版。——译者注

· 据我的经验，当实际需要时再去做模型或写文档比较有效

· 只在遇到麻烦时才更新文档

· 所有文档都应该尽量晚写，应该留到马上要用时再写

所以我们需要的是写文档的时间计划，以及想写随时就能写的环境。那么，什么样的环境能让人随时可以写文档，什么样的环境又能让人有动力写文档呢？或者反过来说，妨碍我们写文档的因素都有哪些呢？下面我们就从 Python 程序员的视角出发，考察妨碍以及促使我们写文档的因素。

7.1.1　写文档时不想做的事

回顾我们以往的经历，那些没有写文档的情况都源于某些共通的理由，下面就介绍其中几个理由。

◉ 不想用写文档的专用工具

写文档时常用的工具有下面这几种。

· 文字处理软件

· 电子制表软件

· Wiki

· 其他综合型工具

这些工具在使用上有许多地方都和我们平时编程用的编辑器不同。为了写文档，必须用自己用不惯的编辑器或工具，这成了写文档时的一大制约。我们更希望能用平常编程用的编辑器写文档。

◉ 不想编辑流水账似的单一文件

一般的文字处理软件都是一个文件管理一篇文档。如果一个文件纵向延伸得较长，我们在编辑或显示内容时就需要将其滚动到特定位置。写文章过程中一旦需要对其他地方进行修改，就必须先滚动到待修改的位置再滚动回来。这种操作往往每写一篇文档就要经历许多次，而且每次寻找原先的位置都很麻烦。

然而这并不是说给工具加个界面分割或是记忆位置的功能就能行的。问题的根源在于一个文档以一个大文件的形式被管理着。这就像一个程序员肯定会觉得可分割的源码写在一个文件里十分影响效率一样。

要解决这个问题，应该像源码一样将文档分割成多个文件管理。

◉ 不能用 Mercurial 等管理差别，让人生厌

用文字处理软件写出的文档是单一的二进制文档，不管我们在里面修改了几个字、几段文章或者几幅图片，Mercurial 等版本控制系统都无法掌握该文件中的被修改之处。另外，如果有好几个人编辑同一个文件，很容易出现变更冲突，而且无法事后自动整合双方的变更。

由于存在着这些问题，我们很难放心大胆地去添加变更。

◉ WYSIWYG 工具在装饰和显示上很费时间

WYSIWYG 是 What You See is What You Get 的简写，意思是“所见即所得”。顾名思义，用 WYSIWYG 类工具写文档时能直接看到文档最终的显示或装饰效果。

不过，这有时也会让我们在写文章时分心去考虑显示效果，在装饰和显示上花费多余时间。

◉ 不想把参考资料和程序分开写

极限编程等敏捷过程问世以来，人们对程序的概念发生了变化，那就是从“程序是按设计书写的一成不变的东西”变成了“程序是阶段性变化的东西”。

在程序阶段性变化的过程中，文档必须跟着程序的脚步进行更新。如果文档没能跟上程序的变化，看文档的人就会按照陈旧的错误信息去写程序，导致开发无法顺利进行。

其实，人们很早以前就开始借助专门工具来解决这一问题了。这些工具可以自动将函数定义附近的 API 文档反映到参考文档中。但可惜的是，有些编程语言无法使用这类工具。

所以我们需要一个轻松的联动机制，保证 API 和函数的实现与参考文档的内容不出现错位。

◉ 不想写没人看的文档

没人看的文档根本没必要写。那么，我们应该如何分辨一个文档有没有人看呢？

写出来的文档没人看，主要原因是这个文档的目的不够明确，让人不知道是写给谁的，为什么写的。所以在项目的早期阶段就该给文档做好计划，规定好什么时候写、为了什么目的而写，以及需要写什么内容。

如果写文档的目的不明确，那写出来的内容也不可能明确。有了一个明确的目的，不但能让我们有机会讨论是不是有必要写这个文档，而且写起来脑中也能有明确的内容。

有些时候，我们会遇到一些必须写的文档，但这些文档又不大可能有人来读。我们也要搞清楚这类文档是为谁写的，为什么要写。如果发现真的没必要写，可以跟委托人商量之后再定夺。

7.1.2　什么样的状态让人想写文档

我们前面考察了妨碍写文档的因素，那么什么样的情况能让我们更愿意写并且更轻松地写文档呢？

消除了妨碍因素，掌握写文档时的关键点后，以下几个“让人愿意写文档并能轻松写文档的条件”就自然而然地浮现了出来。

· 能在平时用的编辑器上写文档

· 能把文档分成几个文件来写

· 能用 Mercurial 等轻松实现版本管理

· 能集中精神编辑内容，不用顾虑装饰等外观问题

· API 参考手册与程序的管理一体化

· 平时的引用可通过 Web 浏览器共享

· 在提交文档时可转换成漂亮整齐的单一文件

· 写有用的文档

那么，满足这些条件的文档编辑环境有哪些呢？

如今市面上有很多文档编辑工具，它们各有各的特点，也各有各的长项与短项。这里我们从文档结构的观点出发，来了解一下这些特点的差异。

Wiki 是用来构筑半格（Semilattice）结构文档的工具。半格结构没有起点和终点，是一种各元素之间依靠引用链相连的网状结构。这种结构适合在某一主题下以不断添加关键字的形式编写文档片段。相反地，它不适合编写那种要从头到尾按顺序阅读并提交的文档。

与此相对的还有构筑树结构的工具。树结构存在起点，起点元素之下的各元素有着固定的从属关系。以图书为例，目录页下挂着各章的标题，各章下又挂着各节的标题。树结构的文档适合从头到尾按顺序阅读。不过，单纯的树结构在很多情况下都不大好用，所以我们会添加一个到任意元素的引用，将树结构改造成网状结构。虽然树结构看上去优于半格结构，但它必须有一个主干，所以不适合用来当没有固定结构的字典。

接下来我们将学习 Sphinx，它是构筑树结构文档的文档编辑工具。

Sphinx 是用 Python 编写的工具，用来构建多个以 reStructuredText 语法编写的文本文件，将它们转换为 HTML 或 PDF 等格式。Sphinx 可以将树的各个元素分割成多个文件进行管理。另外，这款工具的功能和特征满足刚才我们说过的“让人愿意写文档并能轻松写文档的条件”中的许多条，甚至能让人更加主动地想要写文档。

NOTE

当然，只要讲究方法、肯下功夫，不管什么工具都有可能让我们达到目的，但其过程是否给人带来压力就另当别论了。我们即将学习的 Sphinx 也完全不是那种在 GUI 中随便一操作就能写文章的工具，但它适合像写程序一样结构化地写文章。

接下来，我们将先来了解一下 Sphinx 的基本使用方法。然后根据本节列出的这些条件，分条学习如何用 Sphinx 实现它们。