API Reference

sphinx_add_docs(NAME ARGV)

Convenient function for adding a target for generating documentation with Sphinx:

sphinx_add_docs(NAME
    [ALL]
    [COMMENT comment]
    [WORKING_DIRECTORY dir]
    [BUILDER name]
    [CONFIG_DIRECTORY path]
    [SOURCE_DIRECTORY dir]
    [OUTPUT_DIRECTORY dir]
    [DEFINE setting1=value1 setting2=value2...]
    [DEPENDS target1 target2...]
    [LIBRARY_PATH_PREPEND path1 path2...]
    [PYTHON_PATH_PREPEND path1 path2...]
    [ENVIRONMENT env1 env2...]
    [SHOW_TRACEBACK]
    [WRITE_ALL]
    [FRESH_ENV]
    [ISOLATED]
)

The options are:

• NAME

  Indicate the name of the target that will be created.

• ALL

  Indicate that this target should be added to the default build target so that it will be run every time.

• COMMENT

  Display the given message before the commands are executed at build time. By default the following value will be used:

  sphinx_add_docs(
      ...
      COMMENT "Generate documentation for ${NAME}"
  )
  

• WORKING_DIRECTORY

  Specify the directory in which to run the Sphinx command. If this option is not provided, the current source directory is used.

• BUILDER

  Specify a Builder to use for generating the documentation. If this option is not provided, the “html” builder is used:

  sphinx_add_docs(
      ...
      BUILDER html
  )
  

• CONFIG_DIRECTORY

  Specify the directory in which to look for the conf.py file. If this option is not provided, the conf.py is expected to be found in the source directory:

  sphinx_add_docs(
      ...
      CONFIG_DIRECTORY /path/to/config/
  )
  

• SOURCE_DIRECTORY

  Specify the directory in which documentation source files are located. If this option is not provided, the current source directory is used:

  sphinx_add_docs(
      ...
      SOURCE_DIRECTORY /path/to/source/
  )
  

• OUTPUT_DIRECTORY

  Specify the directory in which documentation will be generated. If this option is not provided, a “doc” directory within the current binary directory is used:

  sphinx_add_docs(
      ...
      OUTPUT_DIRECTORY /path/to/output/doc
  )
  

• DEFINE

  Override a configuration value set in the conf.py file. The value must be a number, string, list or dictionary value. For lists, use commas to separate values; for dictionaries, use dots to represent hierarchical keys; and for boolean values, use 0 or 1:

  sphinx_add_docs(
      ...
      DEFINE
          "html_theme_path=path1,path2"
          "latex_elements.docclass=scrartcl"
          "show_authors=1"
  )
  

• DEPENDS

  List of dependent targets that need to be executed before generating the documentation:

  sphinx_add_docs(
      ...
      DEPENDS lib1 lib2
  )
  

• LIBRARY_PATH_PREPEND

  List of library paths to prepend to the corresponding environment variable (LD_LIBRARY_PATH on Linux, DYLD_LIBRARY_PATH on macOS, and PATH on Windows) when building the documentation. Each path can be defined literally or as a CMake expression generator for convenience:

  sphinx_add_docs(
      ...
      LIBRARY_PATH_PREPEND
          $<TARGET_FILE_DIR:lib1>
          $<TARGET_FILE_DIR:lib2>
          /path/to/libs/
  )
  

• PYTHON_PATH_PREPEND

  List of Python paths to prepend to the PYTHONPATH environment variable when building the documentation. Each path can be defined literally or as a CMake expression generator for convenience:

  sphinx_add_docs(
      ...
      PYTHON_PATH_PREPEND
          $<TARGET_FILE_DIR:lib1>
          $<TARGET_FILE_DIR:lib2>
          /path/to/python/
  )
  

• ENVIRONMENT

  List of custom environment variables with associated values to set when building the documentation:

  sphinx_add_docs(
      ...
      ENVIRONMENT
          "ENV_VAR1=VALUE1"
          "ENV_VAR2=VALUE2"
          "ENV_VAR3=VALUE3"
  )
  

• SHOW_TRACEBACK

  Display the full traceback when an unhandled exception occurs. Otherwise, only a summary is displayed and the traceback information is saved to a file for further analysis:

  sphinx_add_docs(
      ...
      SHOW_TRACEBACK
  )
  

• WRITE_ALL

  Indicate whether all output files should always be written, instead of only writing output for changed source files:

  sphinx_add_docs(
      ...
      WRITE_ALL
  )
  

  Note

  This option does not re-read source files. To read and re-process every file, use FRESH_ENV instead.

• FRESH_ENV

  Rebuild environment for every source files instead of only generating output for changed source files:

  sphinx_add_docs(
      ...
      FRESH_ENV
  )
  

• ISOLATED

  Ignore any discovered conf.py file:

  sphinx_add_docs(
      ...
      ISOLATED
  )
  

Note

This function works similarly to the doxygen_add_docs function, which generating documentation for Doxygen.