Tutorial

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

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 build the documentation as part of the project.

The sphinx-build command can be implemented directly 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 directory, making it ready for installation or deployment.

In some cases, the documentation build may depend on Python modules or shared libraries produced by the project itself. These must be made available through the build environment.

This can be achieved by explicitly defining environment variables on the target, for example:

set_target_properties(doc PROPERTIES
    ENVIRONMENT
        PYTHONPATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{PYTHONPATH}
)

Similarly, shared libraries required at runtime must be discoverable through the platform-specific library search path.

set_target_properties(doc PROPERTIES
    APPEND ENVIRONMENT
        LD_LIBRARY_PATH=$<TARGET_FILE_DIR:MyLibrary>:$ENV{LD_LIBRARY_PATH}
)

Warning

The environment variable used to locate shared libraries depends on the platform. LD_LIBRARY_PATH is used on Linux, DYLD_LIBRARY_PATH on macOS, and PATH on Windows.

Using the function

A sphinx_add_docs() function is provided to simplify the creation of a documentation target. The configuration above can therefore be replaced by the following:

sphinx_add_docs(doc ALL)

By default, the builder used is html. Another builder can be selected as follows:

sphinx_add_docs(doc ALL
    BUILDER latex
)

Different source and output directories can be specified:

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

A separate directory can also be used to locate the conf.py file:

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

Configuration values can be overridden directly from the CMake configuration using the DEFINE option:

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

The conf.py file can be ignored entirely if required:

sphinx_add_docs(doc ALL ISOLATED)

When the documentation depends on project-built libraries or Python modules, the build environment can be configured declaratively using dedicated options.

The LIBRARY_PATH_PREPEND option prepends directories to the platform-specific library search path, selecting the appropriate environment variable automatically:

sphinx_add_docs(doc ALL
    LIBRARY_PATH_PREPEND
        $<TARGET_FILE_DIR:MyLibrary>
)

Python modules can similarly be made available by prepending directories to the Python module search path:

sphinx_add_docs(doc ALL
    PYTHON_PATH_PREPEND
        ${CMAKE_CURRENT_SOURCE_DIR}/python
)

Custom environment variables can also be defined explicitly:

sphinx_add_docs(doc ALL
    ENVIRONMENT
        "MY_PROJECT_DOCS_MODE=1"
        "CUSTOM_FLAG=enabled"
)

These options allow the documentation build environment to be described declaratively and consistently across platforms, without manually handling platform-specific environment variables.