Question

正如在前面提到过的，文档是软件开发的重要组成部分。但是，仍然有很多项目缺乏很好的文档。文档编写被看作是复杂而艰巨的任务，但其实大可不必如此。利用一些Python程序员可用的工具，可以令代码的文档编写工作就像写代码一样容易。

导致文档稀少或干脆没有文档的最大元凶之一就是，很多人想当然地认为文档只能手工编写。即使有多个人做同一个项目，也只是意味着最终会有一个或多个人不得不疲于应付编程并维护文档。而且如果你问任何一个开发人员更喜欢做哪种工作，他们肯定会说他们宁愿开发软件而不愿意为软件写文档。有时文档的流程甚至完全独立于开发流程，这意味着可能写文档的人甚至从来没有实际写过一行代码。而且，任何这种方式生成的文档很可能是过时的。不管文档是由程序员自己来完成还是有专门的文档编写人员来完成，纯手工的文档编写方式几乎都不可能跟上开发节奏的。

归根结底，代码和文档离得越远，对文档的维护就越难。所以说，为什么要让代码和文档完全分开呢？实际上不仅可以直接将文档放到代码里，而且可以很容易地将文档转换成可读的HTML或者PDF文件。

Python中文档格式的事实标准是reStructuredText，或简称reST。它是一种轻量级的标记语言（类似流行的Markdown），在易于计算机处理的同时也便于人类读写。Sphinx（http://sphinx-doc.org/）是处理这一格式最常用的工具，它能读取reST格式的内容并输出其他格式的文档。

项目的文档应该包括下列内容。

· 用一两句话描述这个项目要解决的问题。

· 项目所基于的分发许可。如果是开源软件的话，应该在每一个代码文件中包含相应信息。因为上传代码到互联网并不意味着人们知道他们可以对代码做什么。

· 一个展示项目如何工作的小例子。

· 安装指南。

· 指向社区支持、邮件列表、IRC、论坛等的链接。

· 指向bug跟踪系统的链接。

· 指向源代码的链接，以便开发人员可以下载并立刻投入开发。

还应该包括一个README.rst文件，解释这个项目是做什么的。这个README文件会显示在GitHub（https://github.com/）或PyPI（http://pypi.python.org）的项目页面上。两个网站都可以处理reST格式。

提示

如果正在使用GitHub，那么也可以添加一个CONTRIBUTING.rst文件，这个文件会在有人创建pull请求时显示。它应该给出一组检查项以便开发人员在提交代码之前对照检查，如遵守PEP 8或者不要忘记运行单元测试。

提示

Read The Docs（http://readthedocs.org）可以自动在线生成和发布文档。在上面注册并配置项目是一个很直接地流程，它会搜索Sphinx配置文件，构建文档，然后让用户可以访问文档。它是代码托管网站的非常好的搭配。