doxygen + doxypypy + docstring 生成python文档
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