用epydoc从python代码中直接生成文档

在一个大的项目里，或在接手别人项目时才知道文档是多么重要，以后写代码时也要多写写文档，实在没有文档，注释也要多写写。今天晚上本来是想看看pynotify的，没文档，需要自己生成，这一下就让我想到，如果我也这么干，以后写注释就是写文档了。他得文档生成工具是epydoc， 用了一下还是很简单，非常不错，学习之。

先要安装epydoc和graphviz ，arch的源上都有，相信ubuntu也肯定有。

然后代码里加上注释， 我写了个demo，文件名是tepydoc.py

[python] view plaincopyprint?

1. #!/usr/bin/env python  
2. #coding: utf-8  
3. ''''' 
4. @author: Arthur 
5. @license: *** 
6. @contact: ****@***** 
7. @see: http://wenku.baidu.com/view/1d2ac17fa26925c52cc5bf92.html 
8.  
9. @version: 0.0.1 
10. @todo[0.0.2]: a new story 
11.  
12. @note: a comment 
13. @attention: please attention 
14. @bug: a exist bug 
15. @warning: warnings 
16. '''  
17. import sys  
18.   
19. #@var lst: a list variable  
20. lst = [0,1,2,3]  
21. #@type vt: a new type  
22. vt = int  
23.   
24. class ottool:  
25.     ''''' 
26.     Ottool 主类 
27.       -组织其它小工具，完成任务.... 
28.     @todo: we want do is ... 
29.     '''  
30.     def __init__(self):  
31.         ''''' 
32.         初始化函数, 调研其他模块 
33.           -函数很简单，；) 
34.         '''  
35.         self.lst = lst  

再写个Makefile:

[plain] view plaincopyprint?

1. EPYDOC=epydoc  
2. DSTDOC=docstrings  
3.   
4. doc: clean-doc  
5.     $(EPYDOC) --html --graph=all -v -o $(DSTDOC) tepydoc.py  
6.   
7. clean-doc:  
8.     rm -rf $(DSTDOC)  
9.   
10. clean: clean-doc  
11.     find . \( -name '*~' -or \  
12.          -name '*.pyc' -or \  
13.          -name '*.pyo' \) \  
14.          -print -exec rm {} \;  

make 一下就可以了，去当前目录docstrings目录下就可以看到生成好的html了。

源码有多个文件也是一样得，只有把代码文件名加上去就可以了， 如：

[plain] view plaincopyprint?

1. $(EPYDOC) --html --graph=all -v -o $(DSTDOC) tepydoc.py tepydoc2.py \  
2.         ttepy/tepydoc3.py  

有些细节可以参考这里： http://wenku.baidu.com/view/1d2ac17fa26925c52cc5bf92.html

epydoc对于一个可以自说明的项目是够的，可以让人很容易了解模块有什么类，有什么函数，大概用处是什么，对于更大或者更复杂得项目就可能无能为力了，django用的是sphinx-build, 用空再看看