【记录】尝试用DocxyGen为Python代码生成文档

【背景】

之前折腾技术的时候,或多或少,知道一个东西:

DocxyGen

是用于从代码生成文档的。

最近,又从:

Seeking very simple ANTLR error handling example when generating C code

->

http://www.antlr.org/api/C/struct_a_n_t_l_r3___b_a_s_e___r_e_c_o_g_n_i_z_e_r__struct.html#b9e9f3d92b4a40a68a877c9689b60f99

该地址无效,但是自己手动输入地址,而找到:

http://www.antlr3.org/api/C/

看到页面右下角,就显示了,此在线文档是通过DocxyGen去生成的。

然后就打算去试试,抽空把我的python代码:

BlogsToWordpress

通过DocxyGen去生成文档看看。

【折腾过程】

1.目前搜到的一些,有参考价值的资料:

(1)官网:

Doxygen usage

介绍了一些基本的使用方法。

(2)Documenting Python using Doxygen

介绍了些最基本的格式。

但是说明的不详细。

(3)Nokia的wiki:

Generate source code documentation with Doxygen

介绍了稍微更详细点。

(4)从:

doxypy: 用 doxygen生成python文档

找到:

http://code.foosel.org/

->

doxypy

->

(5)最终找到官网:

doxygen documentation blocks

然后才是最终最全,最权威的解释:

Comment blocks in Python

不仅解释了格式,并且给出了两种写法的效果:

默认python的doc string的效果:docstring Namespace Reference

支持doxygen自己的特殊命令(special command)的效果(当然效果更好):Class Index

并且也提到了相关参数:

OPTIMIZE_OUTPUT_JAVA

有空好好研究研究。

 

注:

由于已经看到此处官网提到,内在支持python了,所以,无需再用之前的doxypy去将python 的doc string转换为对应的docxygen的格式了。

 

2.有空,直接去看官网最全最系统的资料:

Overview

包含了:

下载和安装

如何快速上手

如何写注释代码

等等内容。

 

3.对应的,很多有价值的资料:

(1)图形化工具:Doxywizard usage

(2)有哪些命令和含义:Special Commands

(3)命令行工具本身如何使用:Doxygen usage

 

4.后来看到:doxypy的升级版doxypypy,貌似做的不错,有机会也可以去试试。

 

【总结】

目前看来,DocxGen,真的是不错的东西。有空需要好好研究研究。



发表评论

电子邮件地址不会被公开。 必填项已用*标注

无觅相关文章插件,快速提升流量