Configuring Doxygen for Documentation Extraction

| Home | Libraries | People | FAQ | More

## Configuring Doxygen for Documentation Extraction

This section details the steps necessary to use Doxygen to extract documentation and comments from source code to build a BoostBook document (and transform it into end-user documentation). You will need a somewhat recent version of Doxygen; 1.2.18 or newer should suffice.

Boost.Build can be configured for Doxygen support by editing `user-config.jam` or `site-config.jam` to add:

    using doxygen : DOXYGEN ;

`DOXYGEN` should be replaced with the name of the doxygen executable (with full path name). If the right doxygen executable can be found via the path, this parameter can be omitted.

### Important

The relative order of declarations in `user-config.jam` / `site-config.jam` files is significant. In particular, `using doxygen` line should come after the `using boostbook` declaration.

Generating of documentation from source files using Doxygen requires two steps. The first step involves identifying the source files so that Doxygen can process them. The second step is to specify that the output of this process, a file in the Doxygen XML format, is input for a BoostBook document. The following `Jamfile.v2` illustrates a simple case of generating reference documentation for the Any library:

    project boost/any/doc ;
    import boostbook : boostbook ;
    import doxygen : doxygen ;

    doxygen any.doxygen : ../../../boost/any.hpp ;
    boostbook any : any.doxygen ;

In this example, we generate the Doxygen XML representation in the file `any.doxygen` from the source file `../../../boost/any.hpp` by invocing Doxygen. We then use `any.doxygen` as a source for the BoostBook target `any`, which will generate documentation in any format the user requests. The actual sequence of events in this transformation is:

1. Doxygen parses the header file `../../../boost/any.hpp` and outputs a single XML file `any.doxygen`.
2. The XSLT processor applies the stylesheet `doxygen2boostbook.xsl` to transform `any.doxygen` into the BoostBook file `any.xml`.
3. The XSLT processor applies the stylesheet `docbook.xsl` to transform `any.xml` into the DocBook XML document `any.docbook`.
4. Further transformations may generate HTML, FO, PDF, etc. from `any.docbook`.

| Copyright © 2003 Douglas Gregor