利用doxygen生成python文档

On and off I have been developing a little Python module to provide KP-ABE and CP-ABE functionality to developers. One important aspect is that of documentation. Any decent project needs to provide both User and Developer documentation. User documentation is
outward facing and tells users how to use the project, and Developer documentation is inward facing and tells developers how the project is structured. Developer documentation is also know as reference documentation. Interestingly, user documentation can be
further divided into two groups: User\u2014for when the user is just a \u2018plain-dumb-user'; and Dev-User\u2014when the project produces something for use by other developers i.e. an library. Often Dev-User documentation is just reference documentation.
This post is concerned with reference documentation.

For documenting API\u2019s and libraries different languages have different tools:

Java has Javadoc, and Doxygen

Python has epydoc, pydoctor, pydoc, sphinx, and Doxygen

C has \u2026 gtk-doc,\u2026, and Doxygen

For design there is always plantuml.

For user documentation, which is not generally tied to a specific programming language there are different formats:

LaTeX

Sphinx

ASCIIDOC

Markdown

reST

DocBook

For developer facing documentation, one can use a combination of the above tools. Especially, when producing UML diagrams.

When I develop code I try to use doxygen everywhere I go, Doxygen is cross language and provides a nice means to produce: End-User, Developer-User, and Developer documentation in HTML, MAN Pages, LaTeX, RTF, and XML; and across multiple languages. This is handed
is you are dropping down into C. Moreover, doxygen has built in support for LaTeX formula within documentation. Furthermore, recent versions of doxygen allow for the use of Markdown, and inclusion of Markdown formatted files. It is essentially the SwissArmy
Knife of documentation.

However, when developing in Python the preferred documentation tool is sphinx, and relies on reST mark up in python \u2018docstrings\u2019, and other files to produce both reference documentation, and user documentation. I find the approach messy, especially
reST.

Helaas, Doxygen doesn\u2019t want to play nice, and prefers to have its documentation place in special comment blocks above method definitions i.e.

##

# Print message to STDOUT

# @param msg The message to be printed

#

def print_message(msg):

print(msg);

and not in docstrings. Luckily there is the doxypy filter that allows one to tell doxygen to look in docstrings. Thus, the above snippet can now become:

def print_message(msg):

""" Print message to STDOUT

@param msg The message to be printed.

"""

print(msg);

To get python and doxygen working nicely together, aside from the standard settings, the following configuration settings are also recommended/required:

INPUT_FILTER = "python /path/to/doxypy.py"

FILTER_SOURCE_FILES = YES

HIDE_UNDOC_RELATIONS = NO

OPTIMIZE_OUTPUT_JAVA = YES

JAVADOC_AUTOBRIEF = YES

MULTILINE_CPP_IS_BRIEF = YES

DETAILS_AT_TOP = YES

EXTRACT_ALL = YES

EXTRACT_STATIC = YES

SHOW_DIRECTORIES = YES

SOURCE_BROWSER = YES

ALPHABETICAL_INDEX = YES

COLS_IN_ALPHA_INDEX = 8

TOC_EXPAND = YES

DISABLE_INDEX = YES

GENERATE_TREEVIEW = YES

Of note, with the latest version of Doxygen you can reference a markdown file as the mainpage.

For an example python project that uses Doxygen, see pyPEBEL.

References:

Automatic Documentation of Python Code using Doxygen

Creating Documentation from Python Source Files with Doxygen and doxypy

Using doxypy for Python code documentation

Use the Readme MD file as main page in Doxygen