Automatic Documentation of Python Code using Doxygen

Posted in Technology, Writing Better Documentation by engtech on March 20, 2007

python doxygen automatic documentation All programming is maintenance programming, meaning that the most value comes from programming code that can be picked up and maintained by someone else. I strongly believe that code and documentation should always go hand in hand. When someone else is trying to modify your code they have no idea they need to read a PDF API document to find out more information about what a function is supposed to do. Whenever documentation exists in a seperate file it always seems to drift away from the code.

A while back I compared several open source tools for automatically generating documentation based on code comments. Doxygen is easily one of the best programs. It was written for C/C++ but there are hacks/filters for getting it working with other languages like Python, Perl and Verilog.

Python comes with a tool for generating documentation called Pydoc, but I don’t like tools that use introspection because they usually choke on weird file import rules. I was elated to find out that they’ve included Python support in Doxygen without having to translating Python to C++. This is a guide for automatically generating documentation off of Python source code using Doxygen.

But don’t take my word for it. There’s lots of other tools available for auto-documenting Python code.

Prerequisites

Assuming Python is installed
Download and install the latest version of Doxygen
Download and install the latest version of GraphViz (not necessary, for creating call graphs)
Download doxypy python filter (not necessary, but adds full support for embedding special syntax to comments)

Generate a Template Doxygen Configuration File

Doxygen is very simple to use, once you have the configuration file set up properly. Use the -g option to generate an example configuration file to get started.

doxygen -g config.dox

or to generate an example configuration file without any comments

doxygen -s -g config.dox

Required Changes to Configuration File

The configuration file can be overwhelming. I still have no idea what some of the options do. These are the settings that are required to change to run Doxygen on python source code. Search for the TAG in the config file.

PROJECT_NAME = Name of the project.
               Use quotes if it is more than one word.
OUTPUT_DIRECTORY = Where the doxygen output files
                   will be created.
INPUT = Where the python source code is.
FILE_PATTERNS = *.py if you want to only generate
                for python files.
RECURSIVE = YES if the python files are in sub-directories.

Optional Changes to Configuration File – Adding a Filter

pythfilter by Matthias Baas (2003) – converts Python to C++ stubs, no longer works now that Doxygen supports Python

Doxypy by foosel and demod (2006) – converts Python docstrings to Doxygen special documentation blocks, allowing you to use Doxygen/Javadoc syntax

Make sure doxypy.py is executable and that you are using it with a fairly new version of Python (2.3 or higher) because it uses the enumerate() built-in function.

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

Optional Changes to Configuration File – Generating Call Graph Images

Doxygen can generate call graph images in the documentation if you have the DOT tool installed (part of GraphViz). This didn’t work well for me — it generated graphs for class hierarchy but did not generate function call graphs (too bad).

Show call graphs even if there isn’t documentation for the functions.

HIDE_UNDOC_RELATIONS   = NO

DOT is installed.

HAVE_DOT               = YES

Generate call graphs (slow).

CALL_GRAPH             = YES
CALLER_GRAPH           = YES

Specify the path to DOT if it isn’t on your system $PATH.

DOT_PATH               = path/to/dot

Optional Changes to Configuration File – More Documentation

These are some settings that I like to use to generate as much documentation as possible. Search for the TAG in the config file.

Treat multiline comment blocks as a brief description.

MULTILINE_CPP_IS_BRIEF = YES

Output a detail description at the top of the documentation.

DETAILS_AT_TOP         = YES

Show all class members even if they aren’t documented.

EXTRACT_ALL            = YES

EXTRACT_STATIC         = YES

Show directory hierarchies in documentation.

SHOW_DIRECTORIES       = YES

Include version numbers of files.

FILE_VERSION_FILTER    = "cvs version -q"

Include source code in the documentation.

SOURCE_BROWSER         = YES

Generate an index file (useful for big projects).

ALPHABETICAL_INDEX     = YES
COLS_IN_ALPHA_INDEX    = 8
TOC_EXPAND             = YES
DISABLE_INDEX          = YES
GENERATE_TREEVIEW      = YES

Use frames and generate a tree.

GENERATE_TREEVIEW      = YES

I don’t use the latex documentation.

GENERATE_LATEX         = NO

Run Doxygen

Once you have the configuration file sorted out, doxygen itself is simple to run.

doxygen config.dox

Unfortunately the current version I’m using (1.5.1) has some display issues with the HTML syntax highlighted output of python source files that required post-processing, but hopefully that will be fixed in future versions.