利用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