码迷,mamicode.com
首页 > 编程语言 > 详细

doxygen + doxypypy + docstring 生成python文档

时间:2014-08-24 22:21:33      阅读:241      评论:0      收藏:0      [点我收藏+]

标签:python   doxygen   docstring   文档化   

1 原生doxygen对python注释的文档化支持情况

默认情况下,doxygen可以同时支持两种风格的python注释,原生的docstring和类似java doc风格的##。不过实际使用时不是十全十美

"""@package docstring
Documentation for this module.

More details.
"""

def func():
    """Documentation for a function.

    More details.
    """
    pass

类似java doc风格的##

#  Documentation for this module.
#
#  More details.

## Documentation for a function.
#
#  More details.
def func():
    pass

  • 可惜的是,对原生的docstring,在函数多行定义的时候,不仅经常提取不到注释,而且即使提取到注释,也不支持各种注释tag,如@param,@see等。
  • 对java doc风格的##,虽然支持较好,可惜的是偶使用的是pydev做IDE工具的,pydev显示函数注释信息总是错位的,提取的是下一个函数的注释。


2. input filter:doxypypy

幸运的是,有牛人提供了一个doxygen的input filter,用于把原生docstring转换为java doc风格的##。https://github.com/Feneric/doxypypy。注意还有一个类似的叫doxypy的工具,是现在这个工具的前身,那个工具问题不少。


这里先简单介绍一下doxygen的input filter的功能,简单一句话描述就是一个文本的预处理。当你定义了input filter之后,doxygen在生成文档时就不会直接读取文件内容,而是先调用input filter处理文件内容,然后将处理结果作为doxygen自己的输入。

再简单介绍一下doxypypy这个工具的工作原理:简单来说就是先提取出docstring,然后去掉docstring开头和结尾的""", 然后插入##作为第一行,再在其余各行注释前面加上#,这样就很简单巧妙的转换为类java doc的##风格了。将转换后的结果作为doxygen的输入,就可以制作出漂亮的文档了。

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


def complex(real=0.0, imag=0.0):
    """Form a complex number.

    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)

    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)

经过转换之后,就变成

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


##Form a complex number.
#
#    Keyword arguments:
#    real -- the real part (default 0.0)
#    imag -- the imaginary part (default 0.0)
#
#
def complex(real=0.0, imag=0.0):
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)


甚至,你还可以配置脚本运行参数,自动从某种tag风格装换为固定的@tag的风格,还是以上面为例

# As close as possible to a direct copy of the sample in PEP 257 and still
# be valid code. Simple as can be.

complex_zero = 0j


## @brief Form a complex number.
#
#
# @param		real	the real part (default 0.0)
# @param		imag	the imaginary part (default 0.0)
#
#
# @namespace sample_pep.complex
def complex(real=0.0, imag=0.0):
    if imag == 0.0 and real == 0.0:
        return complex_zero
    else:
        return complex(real, imag)

3 添加doxypypy对中文的支持

解释的话稍微多了点,下面说一下中文支持。原生的doxypypy工具不支持中文。想鄙人这种没有专业八级英语的,写的注释有时还不如不写。不过要支持也简单,使用下面这个补丁。不多说,就两点:使用codecs按utf-8编码格式读入,将标准输出的编码设置为utf-8。

diff --git a/doxypypy/doxypypy.py b/doxypypy/doxypypy.py
old mode 100755
new mode 100644
index 833a723..76ca6be
--- a/doxypypy/doxypypy.py
+++ b/doxypypy/doxypypy.py
@@ -20,6 +20,8 @@
 from os import linesep
 from string import whitespace
 from codeop import compile_command
+import codecs
+import sys
 
 
 def coroutine(func):
@@ -820,15 +822,17 @@
 
     # Figure out what is being requested.
     (options, inFilename) = optParse()
-
+    
+    file_encoding = 'utf-8'
     # Read contents of input file.
-    inFile = open(inFilename)
+    inFile = codecs.open(inFilename, encoding=file_encoding)
     lines = inFile.readlines()
     inFile.close()
     # Create the abstract syntax tree for the input file.
     astWalker = AstWalker(lines, options, inFilename)
     astWalker.parseLines()
     # Output the modified source.
+    sys.stdout = codecs.getwriter(file_encoding)(sys.stdout.buffer, 'strict')
     print(astWalker.getLines())
 
 # See if we're running as a script.


4 在doxygen中配置doxypypy

最后说一下如何在doxygen中配置上面工具,直接上图片。注意:doxypypy.py的第一行表示的是python的安装路径,注意修改为自己电脑上的python路径。

bubuko.com,布布扣


如果需要下载修改过的doxypypy.py, 可以在这里下载doxypypy--- Doxygen filter for Python

that‘s all

doxygen + doxypypy + docstring 生成python文档

标签:python   doxygen   docstring   文档化   

原文地址:http://blog.csdn.net/crylearner/article/details/38798455

(0)
(0)
   
举报
评论 一句话评论(0
登录后才能评论!
© 2014 mamicode.com 版权所有  联系我们:gaon5@hotmail.com
迷上了代码!