Tutorial

Once integrated in your project, the Sphinx::Build target and the sphinx_add_docs() function are available for using.

Using the target

Let’s consider a project that includes a doc folder containing Sphinx documentation. We need to add a CMakeLists.txt configuration file to add Python tests within the same directory. The “sphinx-build” command can be easily implemented using a custom target:

add_custom_target(doc ALL
    COMMAND Sphinx::Build -T -b html
    ${CMAKE_CURRENT_SOURCE_DIR}
    ${CMAKE_CURRENT_BINARY_DIR}/doc
)

Building the project will generate an HTML version of the documentation within the build folder, making it ready for installation.

Using the function

A sphinx_add_docs() function is provided to create a target which will generate the documentation. Therefore, the custom target added in the previous section could be replaced by the following:

sphinx_add_docs(doc ALL)

By default, the builder used is “html”. Another builder can be defined as follows:

sphinx_add_docs(doc ALL BUILDER latex)

You can define different source and output directories as follows:

sphinx_add_docs(doc ALL
    SOURCE_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/sphinx-doc
    OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/sphinx-doc
)

You can also define a separate directory to fetch the conf.py file:

sphinx_add_docs(doc ALL
    CONFIG_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}/config
)

Defining configuration setting directly within the CMake configuration file to override the conf.py file can be done as follows:

sphinx_add_docs(doc ALL
    DEFINE
        version=${MAKE_PROJECT_VERSION}
)

If necessary, you can also ignore the conf.py file:

sphinx_add_docs(doc ALL ISOLATED)