Introduction

Doxygen is a powerful in-band documentation program that generates all sorts of docs from source code tags. It works on "C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D."

It can be a pain to get Doxygen up and running, particularly with the still-new Python support, so this page is an attempt to make the process simpler.

Quick reference

See this 2-page PDF for a nice listing of what you most often need.

Prerequisites

On Linux, you can just

apt-get install doxygen graphviz

to get the two main tools you need. (Graphviz is used to generate the diagrams.) On Mac, it's probably easiest to download source and install into /usr/local

and then

fink install graphviz

The last semi-optional piece you need is doxypy. This is due to an annoying limitation of Doxygen and docblocks; it needs to be installed somewhere in the path.

Verify the install

doxygen --version
dot -V
which doxypy.py

Note that you must have 1.5.8 or later of Doxygen to get Python support.

The dot version isn't critical, but both must work and doxypy must be present.

Doxyfile

Doxygen uses a text configuration file named Doxyfile. You can generate an empty skeleton but running

doxygen -g

For Python, several things must be changed. To make it simpler, I've created a skeleton Doxyfile. The skeleton is in our Git repository here or you can checkout the project which also has the automation script:

git clone git@amoeba.ucsd.edu:regulator.git

The Process

1. Save example-Doxyfile as Doxyfile
2. Edit the project name on line 28 and version number on line 34
3. Run doxygen

Output will go to

docs/html

Note that I've selected html-only output, you can easily enable man pages and such if required.

Coding style and tags

Doxygen uses @ tags to markup the code, the main ones I use are

1. @note This will have an indented section on its page, nice for method notes and limitations
2. @bug Doxygen creates a separate bugs page, very nice for notes-to-self-to-fix-this
3. @todo Similar, only to-do instead of a bug
4. @author, @date - Put these in the header of the file
5. @brief Short description of what the file/method/subroutine does
6. @filename Put this in the header of the file - note that case must match the actual filename
7. @param [param name] Use this to document parameters to a function
8. @retval Use this to document the return value of a function

There are lots more tags in the manual, but the short list covers almost all my normal usage.

Note that using @param and @retval greatly increases the usefulness of the documentation. For example:

and with param/retval:

Docblocks

Doxygen gets most of its mojo from parsing marked-up comments, also known as docblocks. With doxypy in place, just comment your code as normal and start sprinkling in @ tags and doxygen'll do the lifting for you.

Output and verification

It's easiest to iterate on getting the results you want, so I suggest starting with a project that just has a few files. See the DOA project for an example. (Code is here in git)

I usually have an editor open and use this command line:

doxygen; open docs/html/index.html

for speed.

And that's about it!

Automation

As of 7/9/09, amoeba is setup to automate the creation of Doxygen docs when you push code into the repository if

1. You've enabled the hook
2. There is a Doxyfile in module's main directory

If you follow the process above to add Doxygen, you're halfway there. Next, you have to do the following on amoeba:

cd /home/git/repositories/[project name.git]/hooks
cat >> post-update
python /home/dev/scripts/post-update.py git@amoeba.ucsd.edu:regulator.git "Regulator" /var/www/doxygen

Where, of course, the git URL and project name match your project. See the Regulator docs for more details.

After that, every push will run doxygen on the server and move the output to the webserver. Cool!