Generating Documentation with Doxygen

The FindDoxygen helper powering our find_package(Doxygen) command provides the convenient doxygen_add_docs() function, which wraps all the logic for creating a documentation target. At its simplest, you give it a name for the target and a list of files or directories to scan.

Let's add it to our Docs.cmake module. We'll create a target named docs and tell it to scan our app and greeter source directories.

1cmake_minimum_required(VERSION 3.23)
2
3find_package(Doxygen)
4if(Doxygen_FOUND)
5  message(STATUS "Found Doxygen Version "
6    "${DOXYGEN_VERSION} at ${DOXYGEN_EXECUTABLE}")
7
8  doxygen_add_docs(docs 
9    ${PROJECT_SOURCE_DIR}/greeter/include 
10    COMMENT "Generating docs with Doxygen..."
11  ) 
12endif()

This single command does several things for us:

1. It creates a custom target named docs.
2. It configures Doxygen to scan files in the provided directories for documentation comments. We're just scanning /greeter in this example, but we could add more.
3. If we don't provide a configuration file, it generates a default one on the fly. We cover configuration files later in the lesson.

With our Docs.cmake module set up and included in our root CMakeLists.txt file, let's configure our project and build our docs. From our build directory:

1cmake ..

Now, we can build our new docs target.

1cmake --build . --target docs

1[build] Generating API documentation with Doxygen...
2... (Doxygen's output) ...

This will create a html/ directory inside our build/ folder. If we open the index.html file in a web browser, we'll see our generated documentation, ready to be explored:

This lets anyone using our library browse through our documentation in a clean, organized way. Our documentation is also a website, so we could easily upload the contents of this /build/html directory on the internet for anyone to browse.

Doxygen's behavior is controlled by a configuration file, by default named Doxyfile. If doxygen_add_docs() can't find this file, it just uses a default configuration it manages internally.

A Doxyfile can set hundreds of settings that controls every aspect of the process, from what files Doxygen should scan to what colors should be used in the generated documentation.

You can generate a default Doxyfile by running doxygen -g in your terminal.

1doxygen -g

1Configuration file 'Doxyfile' created.

This will create a large file that you can copy, paste, and edit as needed. The file is heavily commented, explaining what each option does.

In CMake projects, we don't usually create the Doxyfile directly. Instead, we ask CMake to generate it as part of the configuration step.

The first step is to create a template version of a Doxyfile. We typically call this template Doxyfile.in, whick CMake will ingest and modify to create the final Doxyfile. This allows us to control the configuration through CMake, meaning we can inject CMake variables from our build into the Doxyfile.

Let's create a docs directory in our project root and add our template file to it:

1# High Level Settings
2PROJECT_NAME     = "@PROJECT_NAME@"
3PROJECT_VERSION  = "@PROJECT_VERSION@"
4OUTPUT_DIRECTORY = "@CMAKE_CURRENT_BINARY_DIR@/docs"
5
6# Which files should be documented?
7INPUT     = "@PROJECT_SOURCE_DIR@/greeter/include" \
8            "@PROJECT_SOURCE_DIR@/some-other-lib/include"
9RECURSIVE = YES
10
11# Styling
12HTML_COLORSTYLE     = TOGGLE
13HTML_COLORSTYLE_SAT = 80
14SHOW_INCLUDE_FILES  = NO

In this example, we:

• Provide our project name and version, and where the docs should be generated. We've moved the output to the /docs folder within our /build to keep things more organized.
• Provide a list of the folders that Doxygen should document. The some-other-lib example doesn't exist in our case, but is included to show how we can document multiple directories. The RECURSIVE setting asks Doxygen to also explore subdirectories of these inputs.
• Provide some styling adjustments. The HTML_COLORSTYLE being set to TOGGLE causes the documentation to show a button to switch between light mode and dark mode. HTML_COLORSTYLE_SAT changes the saturation in a range from 0 (grayscale) to 255 (maximum vibrancy). SHOW_INCLUDE_FILES being set to NO hides the list of files that our headers depend on, such as <string>.

This is just an example configuration - Doxygen is hugely configurable. Remember, we can see a full list of options and what they do from the file generated by doxygen -g or, alternatively, from the official docs.

The key part to note for the CMake integration are the @VARIABLE@ placeholders. When we process this file with CMake, it will replace these placeholders with the values of the corresponding CMake variables.

Let's process our Doxyfile.in template to generate a final, configured Doxyfile. We do this with the configure_file() command. This is a generic, CMake-provided command for generating any type of configuration file from a template, not just doxyfiles.

We provide it with an input template (Doxyfile.in in this case) and an output file path. It reads the input, replaces all @VAR@ and ${VAR} placeholders with the corresponding CMake variable values, and writes the result to the output file.

1configure_file(
2  "MyTemplateFile.in"
3  "MyOutputFile.txt"
4)

The @ONLY Argument

The fact that configure_file() replaces placeholders using both the @VAR@ and ${VAR} syntax can be problematic. Some external tools use ${VAR} as their own syntax for interpolating variables, and this includes Doxygen's Doxyfile format.

Without intervention, CMake's configure_file() command would see something like ${DOXYGEN_VAR} in our template, try to substitute it with a CMake variable called DOXYGEN_VAR, find nothing, and replace it with an empty string. This would break our Doxygen configuration.

Fortunately, configure_file() allows us to pass the @ONLY argument. This means it will only replace placeholders that use the @VAR@ syntax, leaving ${VAR} alone:

1configure_file(
2  "Doxyfile.in"
3  "Doxyfile"
4  @ONLY
5)

Using configure_file() to Generate a Doxyfile

Let's use this to create our Doxyfile. We'll stick to the practice of placing generated files in our build directory - CMAKE_CURRENT_BINARY_DIR - so our project is easier to keep clean.

We'll also provide this file to doxygen_add_docs() using the CONFIG_FILE argument, and we can delete our input argument:

1cmake_minimum_required(VERSION 3.23)
2
3find_package(Doxygen)
4if(Doxygen_FOUND)
5  message(STATUS "Found Doxygen Version "
6    "${DOXYGEN_VERSION} at ${DOXYGEN_EXECUTABLE}")
7
8  configure_file( 
9    "${PROJECT_SOURCE_DIR}/docs/Doxyfile.in" 
10    "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" 
11    @ONLY 
12  ) 
13
14  doxygen_add_docs(docs
15    # This is now provided in the Doxyfile<d>
16    ${PROJECT_SOURCE_DIR}/greeter/include
17    
18    CONFIG_FILE "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile" 
19    COMMENT "Generating docs with Doxygen..."
20  )
21endif()

With these changes, we can now rebuild our documentation as before, and see our configuration reflected in the output:

1cmake --build . --target docs

Automating documentation is a common hallmark of creating large projects. By integrating Doxygen with CMake, we can turn a tedious manual task into a simple, repeatable command.

Doxygen Basics: Doxygen generates documentation by parsing special comments (/** ... */) in your source code.

CMake Integration:

1. Use find_package(Doxygen) to locate the Doxygen executable.
2. Use configure_file() to generate a project-specific Doxyfile from your template.
3. Pass the file to the CONFIG_FILE argument of doxygen_add_docs().

Building Docs: After integrating everything, we can generate up-to-date documentation for your project by running a single command: cmake --build . --target docs.

Configuration as Code: Doxygen can be configured using a Doxyfile. We can use CMake to generate this by creating a Doxyfile.in template, and inject variables into the output with @VAR@ placeholders.