ROCMSphinxDoc

Contents

ROCMSphinxDoc#

Applies to Linux and Windows

2024-08-21

3 min read time

Commands#

rocm_add_sphinx_doc#
rocm_add_sphinx_doc(
    SRC_DIR
    BUILDER <sphinx-builder>
    [OUTPUT_DIR <output-directory>]
    [CONFIG_DIR <config-directory>]
    [DEPENDS <doc-targets>...]
    [VARS <sphinx-variables>...]
    [TEMPLATE_VARS <sphinx-variables>...]
    [USE_DOXYGEN]
)

This will create a sphinx-${BUILDER} doc-type target which will generate documentation using sphinx. The SRC_DIR should be the directory that contains the conf.py file.

The options are:

OUTPUT_DIR

The directory where build output will be written. It takes its default, from ROCM_CMAKE_DOCS_DIR if set, otherwise defaults to sphinx/${BUILDER}. Relative paths are interpreted relative to CMAKE_CURRENT_BINARY_DIR.

CONFIG_DIR

The directory where conf.py will be searched. It sets the -c argument of sphinx-build if set, otherwise defaults to ${SRC_DIR} as per the underlying tool. Relative paths are interpreted relative to CMAKE_CURRENT_SOURCE_DIR.

DEPENDS

Sets up target-level dependencies between sphinx-${BUILDER} and the user-provided list of targets.

VARS

List of configuration values passed to Sphinx. List items will be passed as command-line args by prepending -D to each item.

TEMPLATE_VARS

List of HTML template values passed to Sphinx. List items will be passed as command-line args by prepending -A to each item.

USE_DOXYGEN

Flag denoting the use of Doxygen in the fashion rocm-docs-core expects it.

Variables#

SPHINX_EXECUTABLE#

This cached variable can be used to set which sphinx-build executable to use. By default it will search for sphinx-build on the system. The SPHINX_DIR environmental variable is taken as a HINT while searching.

DOXYGEN_EXECUTABLE#

This cached variable can be used to set which doxygen executable to use. By default it will search for doxygen on the system. The DOXYGEN_DIR environmental variable is taken as a HINT while searching.

SPHINX_${BUILDER}_DIR#

This is the directory where the documentation will be built. By default, it will use the OUTPUT_DIR passed to rocm_add_sphinx_doc otherwise it will be set to sphinx/${BUILDER} directory in the cmake build directory.