Generating Doxygen Documents

Generating Doxygen Documents

The bulk of the documentation about ReaK is in the form of doxygen documentation generated from the source files. This page explains the steps to generating the doxygen documentation.

Dependencies

To generate the doxygen documents, the following software is required on your system:

• doxygen: Application that parses C++ source code for especially tagged comments associated to elements of the code (classes, functions, namespaces, concepts, traits, meta-functions, etc.).

• graphviz: Library / application to create nice-looking graph layouts, used by doxygen to generate nice call-graphs, inheritance graphs, and dependency graphs.

• cmake: Build system used throughout this project, also used to drive the generation of doxygen documentation through its platform-independent scripting capabilities.

• git: Version control system (duh!), needed by doxygen to extract version information from the source tree and stamp that information on some doxygen sections of the documentation (i.e. title, authorship, etc.).

Optionally, the cmake doxygen-building script will detect the presence of compressed help file generation capabilities on your system, this is the preferred format to read the documentation (the alternative is html pages). For this purpose, the following applications will be required:

Under Windows:

• HTMLHelp: An application, provided by Microsoft, which can be used to compile compressed help files (i.e. the standard help-file format used throughout Windows applications).

Under Linux:

• Qt4: A graphical user interface library whose SDK includes a program to compile compressed help files which can be opened with Qt4 Assistant (a standard help-file reader by Qt4).

Doxygen Targets in cmake

As mentioned above, cmake is used to drive the doxygen documentation generation. This is achieved via the introduction of custom targets in the cmake build system. In other words, from a user point of view, one generates the cmake build configuration (as you would in a normal build) and then call "make" on the doxygen targets. The procedure is as follows:

1. Create a build directory within the top-level "src" directory:

$ cd /path/to/ReaK/repository/src

$ mkdir build

$ cd build

2. Run cmake on the parent directory:

$ cmake ..

3. Call "make" for the "dox" target, as follows:

$ make dox

The "dox" target is a doxygen target that will generate all the documentation for ReaK. If one wishes to generate only specific parts of the doxygen documentation, there are a number of other targets that generate sub-parts of the doxygen documentation files. Here is the list of targets currently defined:

• dox: An all-inclusive doxygen target to generate all the documentation.
• ReaK_dox: Generates a single doxygen set of documentation which includes all the ReaK source code.
• ReaKallcore_dox: Generates a single doxygen set of documentation which includes all the source files in the ReaK/core folder and its sub-folders.
• ReaKcore_dox: Generates a single doxygen set of documentation which includes only the source files of the core elements of the ReaK framework (core/base, core/rtti, core/serialization, etc.).
• ReaKmath_dox: Generates a single doxygen set of documentation which includes only the source files of the mathematical libraries of ReaK (core/lin_alg, core/kinetostatics, core/integrators, core/root_finders, and core/optimization).
• ReaKctrl_sys_dox: Generates a single doxygen set of documentation which includes only the source files of the "control system" part of the ReaK libraries, at this point, this only includes state estimation code (Kalman filtering code).
• ReaKpp_dox: Generates a single doxygen set of documentation which includes only the source files of the path-planning part of the ReaK libraries. This includes motion-planning algorithms, topological concepts, topologies, motion interpolations, topological mappings, etc.
• ReaKmbd_kte_dox: Generates a single doxygen set of documentation which includes only the source files of the multi-body dynamics modeling part of the ReaK libraries (i.e. the KTE framework).

Notes on how to run doxygen from cmake

The mechanism by which cmake is used to generate the doxygen documents is quite interesting and readers are welcomed to look into the top-level CMakeLists.txt file to see how this is accomplished. The starting point is a package for cmake that allows one to find the "Doxygen" package for cmake to use. Then, the cmake "find_package" utility is used to detect the presence of the above-mentioned dependencies, which are then used in the specification of the build script to be executed on the build of the doxygen custom targets. The actual specification of the doxygen output (the doxygen configuration file) is found in the top-level "src" folder under the name "Doxyfile.in". This file is essentially a template for the doxygen configuration files, with most formatting fields filled out and many fields are empty in order for the build script to fill them out. Two steps must occur, first the script takes the Doxyfile.in file and fills out the relevant fields for a given target such as the target's name, source path, output directory, title, description, input files (source files), and version information (from Git commands); the output of this process is stored as dox/${TARGET_NAME}_Doxyfile in the top-level directory. This step of the process is done in cmake cache and called with the custom cmake command configure_doxyfile. Then, when the target is built (i.e. with "make"), the Doxyfile file for the given target is updated with newest version information into a temporary doxygen configuration file, which is then used to call the doxygen program, and finally call the optional compressed help-file generator if available (Qt or HTMLHelp). To create a doxygen target in the cmake files, one uses the custom command add_doxygen_target.

Feel free to explore this script and copy / modify it for your own needs. This is indeed a great way to automate the doxygen documentation generation, without having to ever manually edit the doxygen configuration files for specific purposes.

Displaying the Doxygen Documentation

Once doxygen targets have been built, you will find, in the top-level "dox" folder, many sub-folders and documents. There will be at least a sub-folder for each target name listed above (except for the umbrella target "dox"). If you also have compressed help-file generators on your system, the compressed help-files of the same name will also appear in the "dox" directory. Under Linux, the show_dox.sh bash script can be used to display the compressed help-files in Qt Assistant. Under Windows, simply open the desired compressed help-file by a double-click. The underlying output format is, of course, HTML. To view the html pages for a given doxygen target, go to the relevant sub-folder and find the "index.html" under the html sub-folder.

Notes on other output formats

One who is familiar with doxygen knows that it offers many output formats and options. One is, of course, free to modify the Doxyfile.in file to change those options in general. However, please note that certain output formats cannot be used in the context of ReaK. One popular output format is LaTeX, however, the ReaK library documentation is simply too big for LaTeX to handle (the last time, years ago, that a pdf-latex could successfully be built from the ReaK doxygen files yielded close to 2000 pages, and since then, latex programs simply run out of memory while parsing the files (by stack overflow!)). The RTF format is another one which could not work due to the sheer size of the documentation. In other words, HTML and compressed derivatives of HTML are the only options for such large projects.