Python部落(python.freelycode.com)组织翻译，禁止转载，欢迎转发。

作为一名开发人员,我们喜欢写代码,虽然它在当时对我们而言很清晰很易懂，但是我们必须考虑我们的读者。有人阅读、使用或着维护我们的代码，他们可能是另一个开发人员,客户,或未来三个月后的自己。即使是像Python这样一门简洁的语言，有时候代码也很难理解。所以作为一名优秀的，同时深切关心同事的程序员(更有可能因为我们的老板希望这样)，我们应该写一些文档。

这是规则：

1.编写文档不能太糟糕（换句话说：我们不能使用微软的word）

2.编写文档必须尽可能容易

3.编写文档不能要求我们放弃我们最喜欢的文本编辑器或IDE。

4.编写文档必须不需要我们定义任何格式或关心最后的陈述。

这是Pycco的来源：

Pycco是Docco的Python接口，Docco是原始的、快速而随意、只有几百行代码、迭代程序风格的文档生成器。它以html的格式在代码旁边显示你的注释。注释是通过Markdown和SmartyPant来显示，代码通过 Pygments 语法高亮。

这意味着Pycco可以为我们自动生成美观的代码文档。Pycco还坚持上面提到的代码文档的四个规则。所以我们怎么会不喜欢它呢？让我通过一些例子来学习如何使用它。

为了写这篇文章，我已经用django写了一个简单TODO 应用作为开始，你可以从repo仓库来获得它。这个应用在完成后允许用户向列表中添加和删除条目。这个应用可能不会让我获得一个威比奖，但是为了这个文章，它应该提供给读者。

请注意,仓库中的文件已经包含最后的代码,并且已经被记录。但你仍然可以创建独立的记录文件，你可以和我一起随意克隆和跟踪仓库。

项目开始：

克隆仓库：

$ git clone git@github.com:mjhea0/django-todo.git

设置变量：

cd django-todo

virtualenv --no-site-packagesvenv

source venv/bin/activate

安装依赖模块：

pip install -r requirements.txt

同步数据库：

cd todopython manage.py

syncdb

生成一些文档

开始很简单：

pip install pycco

然后运行它，命令格式如下：

pycco todos/*.py

注意这种方法可以指定单个文件或目录。在我们的TODO仓库中执行上面的命令会产生以下结果：

pycco = todo/todos/__init__.py -> docs/__init__.html

pycco = todo/todos/models.py -> docs/models.html

pycco = todo/todos/tests.py -> docs/tests.html

pycco = todo/todos/views.py -> docs/views.html

换句话说,它生成的html文件(每个python文件一个)会存储到“文档”目录中。对于较大的项目您可能想要使用- p选项,将保留原始文件路径。

例如---

pyccoo todo/todos/*.py -p

将生成：

pycco = todo/todos/__init__.py -> docs/todo/todos/__init__.html

pycco = todo/todos/models.py -> docs/todo/todos/models.html

pycco = todo/todos/tests.py -> docs/todo/todos/tests.html

pycco = todo/todos/views.py -> docs/todo/todos/views.html

注意在“docs/todo/todos”子目录下它已经为todos应用保存了对应的文档，通过这种方法，它将使得大型项目的文档导航更加容易，同时文档结构将匹配代码结构。

生成文档

pycco目的在于生成双栏文档，即注释在左边，与在右边的后续代码对齐。在还没添加注释的models.py类中，调用pycco，我们将获得一个像下面这样的页面：

你会发现位于左边的列（注释所在的列）仅仅是空白，而右边的列显示的是代码。我们可以通过增加文档描述来改变我们的models.py，通过在models.py增加下面代码从而获得更有趣的文档。

在上面的pycco代码片段中可以找到这一行-

# === Models for Todos app ===

-然后在文档中生成一个描述头。

加入文档字符串：

"""

The ListItem class defines the main storage point for todos.

Each todo has two fields:

text - stores the text of the todo

is_visible - used to control if the todo is displayed on screen

"""

将会被pycco用来生成文档。我们再次运行pycco后结果会是这样：

你可以看到左边的文档和右边的代码对齐工整。这将使得我们回顾代码时理解代码的作用更加容易。

pycco也可以识别代码中以#开头的注释，并生成文档。

变得更精致

pycco不仅仅如此。它还支持使用Markdown对注释进行自定义格式化，例如在views.py文件中加入一些注释，首先让我们在views.py文件的首部加入一些文档字符串。

这将会产生一个报告像这样：

我们可以链接不同的文件，甚至在相同的文件之间也可以做链接。我们可以使用[[filename.py]] 或[[filename.py#section]]来做链接，然后会以文件名链接的方式呈现。

让我们更新views.py，在结尾处为列表中的每个条目加入链接。

正如你所看到的，制作链接需要两个组件，第一我们必须在文档定义一个章节，你可以看到我们已经用代码# === home ===定义了home章节，一旦这个章节被创建，我们可以使用代码[[views.py#home]]来链接它。我们也可以在models文档中插入一个链接，使用下面的代码：

# defined in [[models.py]]

这最后的结果是产生像下面格式类似的文档：

记住因为pycco允许markup语法，你也可以使用完整的html语法，这很疯狂:)

为整个项目自动生成文档

关于如何用pycco为整个项目生成文档的说明可能不是很明显，实际上却很很简单，如果你正在使用bash或者zsh或者任何的被支持sh，你只需运行一个命令，像下面这样：

pycco todo/**/*.py -p

这将为todo的所有.py文件生成文档，如果你正在使用windows，你可以通过cygwin, git bash 或者 power sh来达到这样的目的。

为非python文件生成文档

Pycco还支持其他几种文件类型,这有助于经常使用一种以上的文件类型的web项目。在撰写本文时支持的文件类型的完整列表是：

• .coffee – coffee-script

• .pl – perl

• .sql – sql

• .c – C

• .cpp – C++

• .js – javascript

• .rb – Ruby

• .py – python

• .scm – scheme

• .lua – lua

• .erl – erlang

• .tcl – tcl

• .hs – haskell

这些应该覆盖你所有的文档需求，所以请记住写一些注释让pycco为你生成漂亮的文档。

项目级别的文档pycco表现如何呢？

通常，项目除了代码文档外还有其他的要求——像readme、安装文档、部署文档等等。使用pycco生成上述文档也非常好,这样我们就可以坚持使用一个工具。好吧,在这个时间点上,pycco只会处理上面列表中扩展名的文件。但是没有什么能阻止你创建一个readme.py或install.py文件，并使用pycco生成文档。所有你要做的就是在你的文档放入文档字符串，然后pycco将会生成它,此外它还让你获得完整的markdown支持。想象一下在你的项目根目录下你有一个叫做project_docs的文件夹，其中包含

• install_docs.py

• project_readme.py

• deployment.py

然后你可以运行像下面这样的命令：

pycco project_docs/*.py -p

-在你的docs/project_docs目录中添加适当的HTML文件，当然,这可能是有点普通,但它允许您使用一个工具来生成所有项目的文档。

迭代

pycco还有一个技巧：自动文档迭代。换句话说，你可以让pycco监控你的源代码，并在每次保存源文件时自动生成必要的文档。这是非常有用的，如果你想放入一些自定义的markdown和htm到注释中，并希望确保它正确的呈现。使用自动文档迭代自动运行你只需更改并保存文件然后刷新浏览器，不再需要重复运行pycco命令。

为了达到这个目的你需要安装：pip install watchdog

watchdog是一个可以监控文件变动的模块，安装完成后只需要运行下面的命令-

pycco todo/**/*.py -p --watch

这将会运行pycco并保持在后台持续运行，直到ctrl+c终止。一旦它运行，每次你的源代码更新并保存，将会自动迭代文档，如此方便的文档生成你觉得怎么样？

Pycoo是迄今为止我遇到的最简单和最直接的python代码文档工具。有别人使用其他的吗?提交你的的评论,让我们知道你的想法。干杯!

英文原文：http://www.infoworld.com/article/3175649/analytics/facebook-open-sources-its-prophet-forecasting-tools-for-python-and-r.html

译者：苑雄雄