Automatic Documentation of Python Code using Doxygen
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.
- 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
Once you have the configuration file sorted out, doxygen itself is simple to run.
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.
- Open source automatic source code documentation tools
- Python Essentials
- Teaching children to program using Python
Go in the other direction – Import C/C++ Doxygen comments into Python docstrings using Swig and Doxygen