CMake Cookbook

The CMakeLists.txt file in the src directory is unchanged. The only changes in the root CMakeLists.txt file are as follows:

We include the UseBreathe.cmake custom module:

list(APPEND CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")

include(UseBreathe)

We call the add_breathe_doc function. This function is defined in the custom module, and it accepts keyword arguments to set up the combined Doxygen and Sphinx build:

add_breathe_doc(
  SOURCE_DIR
    ${CMAKE_CURRENT_SOURCE_DIR}/docs
  BUILD_DIR
    ${CMAKE_CURRENT_BINARY_DIR}/_build
  CACHE_DIR
    ${CMAKE_CURRENT_BINARY_DIR}/_doctrees
  HTML_DIR
    ${CMAKE_CURRENT_BINARY_DIR}/html
  DOXY_FILE
    ${CMAKE_CURRENT_SOURCE_DIR}/docs/Doxyfile.in
  CONF_FILE
    ${CMAKE_CURRENT_SOURCE_DIR}/docs/conf.py.in
  TARGET_NAME
    docs
  COMMENT
    "HTML documentation"
  )

Let us examine the UseBreatheDoc.cmake module. This follows the same explicit is better than implicit pattern that we described in the two previous recipes. The module is described in detail, as follows:

The documentation generation depends on Doxygen:

find_package(Doxygen REQUIRED)
find_package(Perl REQUIRED)

We also depend on the Python interpreter and Sphinx:

find_package(PythonInterp REQUIRED)
find_package(Sphinx REQUIRED)

In addition, we must also find the breathe Python module. We use the FindPythonModule.cmake module:

include(FindPythonModule)
find_python_module(breathe REQUIRED)

We define the add_breathe_doc function. This function has a one-value keyword argument, which we will parse using the cmake_parse_arguments command:

function(add_breathe_doc)
  set(options)
  set(oneValueArgs
    SOURCE_DIR
    BUILD_DIR
    CACHE_DIR
    HTML_DIR
    DOXY_FILE
    CONF_FILE
    TARGET_NAME
    COMMENT
    )
  set(multiValueArgs)

  cmake_parse_arguments(BREATHE_DOC
    "${options}"
    "${oneValueArgs}"
    "${multiValueArgs}"
    ${ARGN}
    )

  # ...

endfunction()

The BREATHE_DOC_CONF_FILE template file for Sphinx is configured to conf.py in BREATHE_DOC_BUILD_DIR:

configure_file(
  ${BREATHE_DOC_CONF_FILE}
  ${BREATHE_DOC_BUILD_DIR}/conf.py
  @ONLY
  )

Correspondingly, the BREATHE_DOC_DOXY_FILE template file for Doxygen is configured to Doxyfile in BREATHE_DOC_BUILD_DIR:

configure_file(
  ${BREATHE_DOC_DOXY_FILE}
  ${BREATHE_DOC_BUILD_DIR}/Doxyfile
  @ONLY
  )

We then add our BREATHE_DOC_TARGET_NAME custom target. Note that only Sphinx is run; the necessary calls to Doxygen happen within BREATHE_DOC_SPHINX_FILE:

add_custom_target(${BREATHE_DOC_TARGET_NAME}
  COMMAND
    ${SPHINX_EXECUTABLE}
       -q
       -b html
       -c ${BREATHE_DOC_BUILD_DIR}
       -d ${BREATHE_DOC_CACHE_DIR}
       ${BREATHE_DOC_SOURCE_DIR}
       ${BREATHE_DOC_HTML_DIR}
  COMMENT
    "Building ${BREATHE_DOC_TARGET_NAME} documentation with Breathe, Sphinx and Doxygen"
  VERBATIM
  )

Finally, a status message is printed to the user:

message(STATUS "Added ${BREATHE_DOC_TARGET_NAME} [Breathe+Sphinx+Doxygen] target to build documentation")

After configuring, we can build the documentation as usual:

$ mkdir -p build
$ cd build
$ cmake ..
$ cmake --build . --target docs

The documentation will be available in the BREATHE_DOC_HTML_DIR subdirectory of the build tree. After firing up your browser to open the index.html file, you can navigate to the documentation for the Message class:

Table of Contents for
CMake Cookbook

How to do it

Table of Contents for CMake Cookbook

Table of Contents for
CMake Cookbook