# # Copyright (c) 2019-2020, New York University and Max Planck Gesellschaft. # # License BSD-3 clause # # Build the documentation based on sphinx and the read_the_doc layout. #

#.rst: # # .. cmake:command:: ADD_SPHINX_DOCUMENTATION # # Use breathing cat # to generate documentation for the current project. # # This macro adds a target for the documentation that is only build/installed # if GENERATE_DOCUMENTATION is set (otherwise it has no effect). # # Optional Arguments: # # - DOXYGEN_EXCLUDE_PATTERNS: This argument is not supported anymore! # Setting it will cause an error. It will be complete removed in the # future. # To specify exclude patterns, use a breathing-cat config file instead # (see https://github.com/machines-in-motion/breathing-cat). # macro(ADD_SPHINX_DOCUMENTATION)

cmake_parse_arguments(ADD_SPHINX_DOCUMENTATION

“” # options without arguments “” # options with single argument “DOXYGEN_EXCLUDE_PATTERNS” # options with multiple arguments ${ARGN}

)

if (ADD_SPHINX_DOCUMENTATION_DOXYGEN_EXCLUDE_PATTERNS)
message(FATAL_ERROR

“The DOXYGEN_EXCLUDE_PATTERNS argument is not supported anymore.” “ Documentation is now built by breathing cat, so you can add a” “ breathing_cat.toml file to your repository to add exclude patterns.” “ See documentation of breathing cat for details:” “ https://github.com/machines-in-motion/breathing-cat

) # TODO [2022-10-17]: remove the DOXYGEN_EXCLUDE_PATTERNS argument in half a # year or so.

endif()

if(GENERATE_DOCUMENTATION)

# TODO: This should probably be handled in a nicer way that is more obvious # to the user (probably via an argument that has to be passed? if (DEFINED PYTHON_INSTALL_DIR)

set(PYTHON_PACKAGE_LOCATION

${CMAKE_INSTALL_PREFIX}/${PYTHON_INSTALL_DIR}/${PROJECT_NAME})

else()

set(PYTHON_PACKAGE_LOCATION ${PROJECT_SOURCE_DIR}/python/${PROJECT_NAME})

endif()

# Build and install directories set(SPHINX_DOC_BUILD_FOLDER ${CMAKE_BINARY_DIR}/share/docs/sphinx) set(SPHINX_DOC_INSTALL_FOLDER share/${PROJECT_NAME}/docs/sphinx)

# make sure bcat is installed find_program(BCAT bcat) if(NOT BCAT)

message(FATAL_ERROR

“breathing-cat not found! ” “Please install using: pip3 install breathing-cat”

)

endif()

# Create the output add_custom_target(

${PROJECT_NAME}_sphinx_html ${BCAT} –package-dir “${PROJECT_SOURCE_DIR}”

–output-dir “${SPHINX_DOC_BUILD_FOLDER}” –python-dir “${PYTHON_PACKAGE_LOCATION}” –force

COMMENT “Building documentation for ${PROJECT_NAME}”

)

# install the documentation install(DIRECTORY ${SPHINX_DOC_BUILD_FOLDER}/html

DESTINATION ${SPHINX_DOC_INSTALL_FOLDER})

# Create a dependency on the doc target add_dependencies(doc ${PROJECT_NAME}_sphinx_html)

endif()

endmacro(ADD_SPHINX_DOCUMENTATION)