Learning Epydoc

Epydoc 是什么，Epydoc好吃么？呵呵，这个是Zn在Lilacbbs上留言的模板 :)

先看看这个东西是什么，有什么用，为什么一定要学它？

Epydoc是一个用于Python模块自动生成API文档的工具，主要基于Python模块的文档字符串（docstring），例如Epydoc本省的API文档（html）。一种名叫Epytext轻量级的标记语言被用来标记各种文档字符串，主要是在一些特定的标签上添加相关的信息，例如参数类型等等。Epydoc还可以接受reStructureText，Javadoc以及普通文本格式的docstring。更精彩的例子推荐NLTK的官方API文档。

Epydoc 是纯Python 实现的 Python 专用文档化工具，与Python 结合非常自然，稳定，可扩展，Python代码中的注释采用Epydoc规定的格式来撰写可以非常方便的生成程序的规范化API文档。可以说Epydoc是采用Python按照软件工程开发步骤中不可缺少的一环。

熟悉Python的朋友知道Python还有一个类似的工具可以使用，那就是Pydoc。它和Epydoc的关系是后者能够生成更加丰富和漂亮的文档。

 

下面说说怎么用Epydoc。在网上找了半天，也没有看到一个好的中文资料介绍如何使用这个工具。分为以下几步：

1.安装，参见英文版说明

从sf上下载并安装epydoc-3.0beta1.win32.exe

2.在代码中插入相关的各种格式的Docstring，例如下列标签：

py文献信息

@author: ...作者
@license: ...版权
@contact: ...联系

py状态信息
@version: ...版本推荐使用$Id$
@todo [ver]: ...改进,可以指定针对的版本

py模块信息
@var v: ...模块变量v说明
@type v: ...模块变量类型v说明

py函式信息

@param p: ...参数 p 说明
@type v: ...参数 p 类型说明
@return: ...返回值说明
@rtype v: ...返回值类型说明

py提醒信息

@note: ...注解
@attention: ...注意
@bug: ...问题
@warning: ...警告

py关联信息
@see: ...参考资料

py标签格式
@tag: 内容...

还可以插入url，交叉引用，分块等功能，参见文档化开发注释规范

3.相关工具推荐

现在最喜欢使用的Python IDE是Eclipse + Pydev，今天发现Pydev的Code Style里面可以针对Docstring进行设置，弄好后在编写代码的时候，适当的用Ctrl+1就可以获得自动的Docstring内容，再添加一些就能生成良好的文档了。

4.生成API文档的时候推荐使用GUI方式，省时省力。点击Pydoc安装文档下的gui.py即可。

 

如果是其他的编程语言推荐使用Doxygen，支持C++, C, Java, Objective-C, IDL (Corba and Microsoft flavors) 以及PHP, C# and D 等等语言。

 

总之，我是离不开这个东东了。