Setting up CMake to build your documentation with Doxygen is really quite simple. All you really need is

find_package(Doxygen)
if(${DOXYGEN_FOUND})

        add_custom_target(doc ALL
            COMMAND ${DOXYGEN_EXECUTABLE} Doxyfile.h
            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
            COMMENT "Generating API documentation with Doxygen"
            VERBATIM)

endif() # Doxygen Found

This adds a doc command that builds the documentation and includes it in the ALL rule so that it will be built by default. However, we can make this much smarter. For instance, we can easily make doxygen entirely optional by only enabling it with a CMake option.

Here is the snippet I use in all of my projects now. It uses CMake to generate the Doxyfile with:

  • a version number set by the VERSION_MAJOR, VERSION_MINOR and VERSION_PATH variables.
  • Only enable Doxygen if explicitly requested by setting the -DBUILD_DOCUMENTATION option on the command line
  • An install target

To use it, just copy and paste it into your CMakeLists.txt file.

# The project version number.
set(VERSION_MAJOR   0   CACHE STRING "Project major version number.")
set(VERSION_MINOR   1   CACHE STRING "Project minor version number.")
set(VERSION_PATCH   0   CACHE STRING "Project patch version number.")
mark_as_advanced(VERSION_MAJOR VERSION_MINOR VERSION_PATCH)

find_package(Doxygen)
option(BUILD_DOCUMENTATION
        "Create and install the HTML based API documentation (requires Doxygen)" ${DOXYGEN_FOUND})

if(BUILD_DOCUMENTATION)
    if(NOT DOXYGEN_FOUND)
        message(FATAL_ERROR "Doxygen is needed to build the documentation.")
    endif()

    set(doxyfile_in ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in)
    set(doxyfile ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile)

    configure_file(${doxyfile_in} ${doxyfile} @ONLY)

    add_custom_target(doc ALL
            COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
            WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
            COMMENT "Generating API documentation with Doxygen"
            VERBATIM)

    install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/html
            DESTINATION share/doc)
endif()