Integrating Doxygen into Autotools

Introduction

If you use Doxygen to document your source code, you can integrate it into Autotools so that you can simple type:

$ make doc

to create your code’s documentation.

Adding Doxygen Support

In the top-level Makefile.am, add:

EXTRA_DIST =   bootstrap \
               Doxyfile \
               m4/gnulib-cache.m4 \
               makedoc.sh \
               README.md

DOCS_DIR =     docs

doc docs:
        ./makedoc.sh $(PACKAGE) $(DOCS_DIR)

clean-local:
        rm -fr $(DOCS_DIR)

Specifically, add:

1. Doxyfile (your Doxygen configuration file) and makedoc.sh (a shell script that calls Doxygen) to EXTRA_DIST so they will be included when you type make dist to create a distribution tarball.

2. A DOCS_DIR variable containing the name of the subdirectory into which Doxygen should build the documentation (because using a variable is generally better than hard-coding).

3. Targets doc and docs (so the user can type either and have it work).

4. A clean-local target that allows you to add commands to what happens when the user types make clean. In this case, deletes the generated documentation.

The makedoc.sh script isn’t needed — you could simply run doxygen directly, but it does give a better user experience. When running on macOS, it’ll add the instruction that the user can use macOS’s open command to open the top-level index.html file to view the documentation.

Conclusion

Adding Doxygen support into Autotools is fairly straightforward and makes it easy to generate documentation.

More parts to come!