status

草稿

清风 & liz; 100%

Contents

  1. PCS203 epydoc
    1. 概述
    2. 使用
      1. 安装
      2. 书写格式
      3. 文档生成
    3. 问题

PCS203 epydoc

概述

epydoc是专门用于从源码注释中生成各种格式（如Html, plaintext, LaTeX 和PDF）文档的工具。它支持多种文档化标签语法：Epytext（轻量级的标记语言，用于标记各种文档字符串，主要是在一些特定的标签上添加相关的信息，例如参数类型等等）、ReStructuredText（一种易用的，所见即所得的文本标签语法）、Javadoc（用于Java源代码的文档化标记语言）以及普通文本。

使用

安装

这里先介绍下使用源码安装的步骤： 

~$ wget http://prdownloads.sourceforge.net/epydoc/epydoc-3.0.1.tar.gz #下载
~$ tar zxvf epydoc-3.0.1.tar.gz #解压文件
~$ cd epydoc-3.0.1/ #进入目标目录
~/epydoc-3.0.1$ sudo python setup.py install #安装，需要root权限
[sudo] password for shengyan: 
running install
running build
running build_py
...
#完毕

其他平台下的更多安装方法可参见:

书写格式

使用epydoc生成文档,得先在源代码中插入相关的各种格式的Docstring，它支持多种标签

以下列出基本的标签：

1.   py文献信息   
 '''@author:''' ... 作者 
 '''@license:''' ... 版权 
 '''@contact:''' ... 联系 

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

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

4.   py函式信息   
 '''@param '''p: ... 参数 p 说明 
 '''@type '''v: ... 参数 p 类型说明 
 '''@return: ''' ... 返回值说明 
 '''@rtype '''v: ... 返回值类型说明 

5.   py提醒信息   
 '''@note:''' ... 注解 
 '''@attention:''' ... 注意 
 '''@bug:''' ... 问题 
 '''@warning:''' ... 警告 

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

epydoc 支持三种标签的语法.

  • Epytext: 

     @tag: 内容...

  • ReStructuredText: 

     :tag: 内容...

  • Javadoc: 

     @tag 内容...

更多的Tag语法及注释规范可参见:

文档生成

功能描述:将docstring生成html文档 

   1 # coding: utf-8
   2 def MyFunc():
   3     '''
   4     docstring文档
   5     用epydoc来生成我
   6     '''
   7     pass

运行epydoc来生成文档: 

~$ epydoc pcs-203-1.py

在当前目录下会生成一个html文件夹,点击index.html,即可看到生成的文档结果:

问题

还可以通过书写一个简单的配置文件,生成更丰富的文档.如: 

##可以命名为epydoc.cfg
[epydoc]
# 项目信息，名称及URL
name: Backup
url: http://wiki.woodpecker.org.cn/moin/ObpLovelyPython
#指定想要处理的模块
modules: main.py, inotify.py
#指定输出形式及位置
output: html
target: apidocs/
#指定图形生成工具，这样就可以产生各种UML图
graph: all
dotpath: /usr/bin/dot

然后使用如下命令即可生成所需文档

~$ epydoc --config epydoc.cfg  #获得最新的 API文档