doxygen + doxypypy + docstring 生成python文档

标签：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)

# 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路径。

如果需要下载修改过的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