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.