Doxygen + doxypypy + docstring generate python document

1 native Doxygen documentation support for Python annotations

By default, Doxygen can support both styles of Python annotations, native docstring, and Java doc-like # #. But the actual use is not perfect

"" @package docstringdocumentation for the This module. More details. "" " def func (): "" "    documentation for a function.    More details.    "" " Pass

Java doc style-like # #

#  documentation for the module.## more  details.## documentation for a function.## more  details.def func (): C9/>pass

• Unfortunately, for the native docstring, in the function of multi-line definition, not only often extract comments, and even if extracted to comments, also does not support a variety of comments tag, such as @param, @see and so on.
• Java Doc Style # #, although the support is good, unfortunately I use Pydev do IDE tools, Pydev display function annotation information is always misplaced, extract is the next function comment.

2. Input Filter:doxypypy

Fortunately, there is a Doxygen input filter that converts native docstring to Java doc-style # #. Https://github.com/Feneric/doxypypy. Note that there is a similar tool called Doxypy, which is now the predecessor of the tool, which has a lot of problems.

Here is a brief introduction of the Doxygen input filter function, a simple sentence description is a text preprocessing. When you define input filter, Doxygen does not read the contents of the file directly when it generates the document, but instead calls input filter to process the file contents and then takes the processing result as Doxygen's own input.

A brief introduction to doxypypy how this tool works: simply by extracting the docstring first, then removing the "" "at the beginning and end of the docstring, then inserting the # #作为第一行, and then adding # to the remaining lines of comments, This makes it simple and ingenious to convert the # #风格了 of the class Java doc. With the converted results as input to the Doxygen, you can make beautiful documents.

# as close as possible to a direct copy of the sample in PEP 257 and still# is valid code. Simple as can Be.complex_zero = 0jdef 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 IMA G = = 0.0 and Real = = 0.0:        return complex_zero    else:        return complex (real, imag)

After conversion, it becomes

# as close as possible to a direct copy of the sample in PEP 257 and still# is 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:< C13/>return Complex_zero    Else:        return complex (real, imag)

You can even configure script run parameters to automatically change from a tag style to a fixed @tag style, or take the example above

# as close as possible to a direct copy of the sample in PEP 257 and still# is valid code.  Simple as can Be.complex_zero = 0j## @brief Form a complex number.### @paramrealthe real part (default 0.0) # @paramimagthe  Imaginary part (default 0.0) # # @namespace Sample_pep.complexdef complex (real=0.0, imag=0.0):    if imag = = 0.0 and Real = = 0.0:        return complex_zero    else:        return complex (real, imag)

3 Add doxypypy support for Chinese

Explain the words a little bit more, the following is the Chinese language support. Native Doxypypy tools do not support Chinese. I do not think this is a professional level eight English, write notes sometimes rather than write. But to support is also simple, use the following patch. Not much, just two points: use codecs to read in UTF-8 encoded format, and set the encoding of standard output to utf-8.

diff--git a/doxypypy/doxypypy.py b/doxypypy/doxypypy.pyold mode 100755new mode 100644index 833a723. 76ca6be---a/doxypypy/doxypypy.py+++ b/doxypypy/doxypypy.py@@ -20,6 +20,8 @@ from OS import linesep from string import whi Tespace from codeop import compile_command+import codecs+import sys def coroutine (func): @@ -820,15 +822,17 @@ -820,15 Fig     Ure 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.STD  out = Codecs.getwriter (file_encoding) (Sys.stdout.buffer, ' strict ') print (Astwalker.getlines ()) # See if we ' re running As a script. 

4 Configuring the Doxypypy in Doxygen

Finally, how to configure the above tool in Doxygen, direct slice. Note: The first line of the doxypypy.py represents the Python installation path, which is changed to the Python path on your computer.

If you need to download the modified doxypypy.py, you can download Doxypypy---Doxygen filter for Python here

That ' s all

Doxygen + doxypypy + docstring generate python document