Selective Doxygen

11Dec 2014

Selective Doxygen

Doxygen is a tool for generating documentation for various languages. It is a nice tool and is used in many C++ projects. However, for large projects, generating the documentation can be time consuming. It is therefore often desirable to only generate a subset of the documentation. This allows a developer to only (re-)generate the part which she is working on.

Doxygen itself does not have any parameters to select only a subset to be generated. This article shows how it can be done nevertheless with standard shell features.

Doxygen Options

Doxygen reads its configuration from a file. This file provides enough information to doxygen that a simple call to doxygen does everything. It generates the complete documentation in different formats such as HTML or LaTeX, possibly annotated with hierarchy graphs or any of the other features doxygen provides.

To change the settings, a user usually changes the configuration file and re-runs the tool.

However, doxygen can read from stdin, which is a very powerful feature and allows one to change the configuration on the fly without touching the configuration file. In addition, doxygen does environment variable substitution, which can be used as an alternative in some cases.

Since we are interested in generating only a subset of the documentation, we look at the INPUT parameter. However, the mechanism works for any valid doxygen parameter.

For our example, assume we have a project with a doc folder and some folders with source code in the src directory. The doxygen output shall be generated in the doc folder, but only for the io directory.

src
  - util
  - io
  - fieldbus
  - service
  - os
doc
  - Doxyfile

Using stdin

The general trick is to first output the configuration file, and then overwrite some parameters by appending them. The result can then be piped into doxygen. Any number of parameters can be overwritten with this approach. For our example, we only overwrite the INPUT parameter.

This looks like the following for sh or bash.

( cat Doxyfile ; echo "INPUT=../io" ) | doxygen -

In a fish shell, the command looks like this.

begin; cat Doxyfile ; echo "INPUT=../io"; end | doxygen -

And for Windows, it should work with the following.

( type Doxyfile & echo INPUT=../io ) | doxygen.exe -

Using Environment Variables

In order to use environment variables, one can specify them directly in the configuration file like this.

INPUT = $(INPUT_DIR)

And then configure the environment and run doxygen as usual. Doxygen will do the substitution and execute it accordingly.

export INPUT_DIR=../io
doxygen

This approach works well, but is less flexible as the first approach using stdin. The reason is that one must prepare the variables to use the environment in advance. Also, the environment must be set, otherwise the variables are left unspecified.

A Helping Script

The commands described above are not very difficult. However, to save typing, it is more convenient to put them into a script.

Following is a script that generates the documentation for either all (i.e. what is specified in Doxyfile) or a selection of directories. The script is also available on Github with some additional documentation.

#!/bin/bash

script_dir="$( cd "$( dirname "$0" )" && pwd )"
src_dir=$script_dir
doxygen_opts=$(printf 'OUTPUT_DIRECTORY=%s' "$script_dir") 

# Command to create the complete documentation
if [ $# -eq 0 ]; then
    printf "(cat %s ; printf '$doxygen_opts') | doxygen -" "$script_dir/Doxyfile"
	exit
fi

# Command to create the documentation for selected directories.
selected_dirs=($@)
selected_dirs_array=( "${selected_dirs[@]/#/$src_dir/}" )
doxygen_opts=$(printf 'OUTPUT_DIRECTORY=%s\nINPUT=%s' "$script_dir" "${selected_dirs_array[*]}")
printf "(cat %s ; printf '$doxygen_opts') | doxygen -" "$script_dir/Doxyfile"

References

The Doxygen FAQ has some information about this as well.

Tags: programming