Something went wrong on our end
-
Studer Gabriel authored
As soon as docker image is on external docker registry, the documentation for the singularity container must be updated
Studer Gabriel authoredAs soon as docker image is on external docker registry, the documentation for the singularity container must be updated
CMakeLists.txt 7.62 KiB
# preparing sphinx build
# - setup directories: sources go to BUILD/doc/source
# - every module gets its own directory
# - rst files are copied to this spot
# - compiled documentation goes to STAGE/share/promod3
# list of addtional rst files maintained by the doc dir,
set(_DOC_RST_FILES
index.rst
developers.rst
dev_setup.rst
users.rst
buildsystem.rst
contributing.rst
gettingstarted.rst
portableIO.rst
references.rst
licence.rst
)
add_subdirectory(container)
# add documentation tests (must be done before rest below!)
add_custom_target(doctest)
add_subdirectory(tests)
# set up commands/ vars/ ... for the rst source files
set(_RST_DEPS)
set(_DOC_MODULE_DEPS)
file(TO_NATIVE_PATH "${CMAKE_CURRENT_BINARY_DIR}/source" _RST_SOURCE_DIR)
file(MAKE_DIRECTORY ${_RST_SOURCE_DIR})
# take care of Sphinx config, conf.py; will be created from conf.py.in since
# some values from CMake have to be substituted
set(_SPHINX_CONF_PY "${_RST_SOURCE_DIR}/conf.py")
set(_SPHINX_CONF_SUBST_DICT PROMOD3_VERSION_MAJOR="${PROMOD3_VERSION_MAJOR}"
PROMOD3_VERSION_MINOR="${PROMOD3_VERSION_MINOR}"
PROMOD3_VERSION_PATCH="${PROMOD3_VERSION_PATCH}"
PYTHON_DOC_URL="${PYTHON_DOC_URL}"
LIB_STAGE_PATH="${LIB_STAGE_PATH}"
PYTHON_MODULE_PATH="${PYTHON_MODULE_PATH}"
OST_PYMOD_PATH="${OST_PYMOD_PATH}"
OST_DOC_URL="${OST_DOC_URL}"
LIB_DIR="${LIB_DIR}"
THIS_DIR="${_RST_SOURCE_DIR}"
PROJECT_SOURCE_DIR="${PROJECT_SOURCE_DIR}")
set(_CONF_SUBST_DICT -DINPUT_FILE=${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in)
list(APPEND _CONF_SUBST_DICT -DOUT_FILE=${_SPHINX_CONF_PY})
foreach(_subst ${_SPHINX_CONF_SUBST_DICT})
list(APPEND _CONF_SUBST_DICT -D${_subst})
endforeach()
add_custom_command(OUTPUT ${_SPHINX_CONF_PY}
MAIN_DEPENDENCY "${CMAKE_SOURCE_DIR}/CMakeLists.txt"
DEPENDS "${CMAKE_CURRENT_SOURCE_DIR}/conf.py.in"
COMMAND ${CMAKE_COMMAND} ${_CONF_SUBST_DICT}
-P ${CMAKE_SOURCE_DIR}/cmake_support/substitute.cmake)
# also move cmake domain (cmake.py) to the dir to build doc
file(TO_NATIVE_PATH "${_RST_SOURCE_DIR}/cmake.py" _SPHINX_DOMAIN_CMAKE_PY)
file(TO_NATIVE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake.py" _CSD_SPHINX_DOMAIN_CMAKE_PY)
add_custom_command(OUTPUT ${_SPHINX_DOMAIN_CMAKE_PY}
MAIN_DEPENDENCY "${_CSD_SPHINX_DOMAIN_CMAKE_PY}"
COMMAND ${CMAKE_COMMAND} -E copy
"${_CSD_SPHINX_DOMAIN_CMAKE_PY}" "${_SPHINX_DOMAIN_CMAKE_PY}")
set(_RST_DEPS ${_RST_DEPS} "${_SPHINX_DOMAIN_CMAKE_PY}")
# the reStructuredText files from the doc directory have to be moved to the
# build dir to work with SPHINX
foreach(_rst_file ${_DOC_RST_FILES})
add_custom_command(OUTPUT "${_RST_SOURCE_DIR}/${_rst_file}"
MAIN_DEPENDENCY "${CMAKE_CURRENT_SOURCE_DIR}/${_rst_file}" COMMAND ${CMAKE_COMMAND} -E copy
"${CMAKE_CURRENT_SOURCE_DIR}/${_rst_file}" "${_RST_SOURCE_DIR}/${_rst_file}")
set(_RST_DEPS ${_RST_DEPS} "${_RST_SOURCE_DIR}/${_rst_file}")
endforeach()
# care for a changelog file, if given
if(DEFINED PM3_DOC_CHANGELOG)
# copy to different file name
add_custom_command(OUTPUT "${_RST_SOURCE_DIR}/changelog.rst"
MAIN_DEPENDENCY "${PM3_DOC_CHANGELOG}"
COMMAND ${CMAKE_COMMAND} -E copy
"${PM3_DOC_CHANGELOG}" "${_RST_SOURCE_DIR}/changelog.rst")
set(_RST_DEPS ${_RST_DEPS} "${_RST_SOURCE_DIR}/changelog.rst")
endif()
# iterate list of ALL modules registered by pymod()/ add_doc_source()
foreach(mod ${PM3_PY_MS})
# only modules with dedicated rst files are considered for documentation, so
# we check if a list PM3_RST_{module name} exists (filled by add_doc_source()
# the following sets up copying for *.rst files only
if(DEFINED PM3_RST_${mod})
# this is a list of rst files, of which everyone becomes a Make target
foreach(rst ${PM3_RST_${mod}})
# the list comes with full path, the targets point towards the build dir
# so we need to extract the filename
get_filename_component(rst_name ${rst} NAME)
set(_RST_SOURCE_MOD_DIR "${_RST_SOURCE_DIR}/${mod}")
# create directory, since it does not come with any CMake file, it will
# not be created by CMake
file(MAKE_DIRECTORY ${_RST_SOURCE_MOD_DIR})
set(_RST_OUTPUT "${_RST_SOURCE_MOD_DIR}/${rst_name}")
add_custom_command(OUTPUT "${_RST_OUTPUT}"
MAIN_DEPENDENCY "${rst}"
DEPENDS ${PM3_DOC_DEPS_${mod}}
COMMAND ${CMAKE_COMMAND} -E copy ${rst} ${_RST_OUTPUT})
# for other targets, create a list of all modules doc depends on
foreach(md ${PM3_DOC_DEPS_${mod}})
list(FIND _DOC_MODULE_DEPS ${md} _check_red)
if("${_check_red}" MATCHES "-1")
list(APPEND _DOC_MODULE_DEPS "${md}")
endif()
endforeach()
# we need a list of dependencies to create the effective targets, since
# in our custom_commands we are dealing with file targets
set(_RST_DEPS ${_RST_DEPS} ${_RST_OUTPUT})
endforeach()
endif()
endforeach()
# add dependencies from doctests
list(APPEND _DOC_MODULE_DEPS "${PM3_DOC_DEPS_doctests}")
# create targets for sphinx
# for the html target, we make everything depend on index.html
set(_SPHINX_HTML_DIR "${SHARED_DATA_PATH}/html")
file(MAKE_DIRECTORY ${_SPHINX_HTML_DIR})
set(_SPHINX_INDEX_HTML "${_SPHINX_HTML_DIR}/index.html")
add_custom_command(OUTPUT ${_SPHINX_INDEX_HTML}
MAIN_DEPENDENCY "${_SPHINX_CONF_PY}"
DEPENDS ${_RST_DEPS} ${_DOC_MODULE_DEPS}
COMMAND ${SPHINX_BINARY} -b html -c "${_RST_SOURCE_DIR}"
"${_RST_SOURCE_DIR}" "${_SPHINX_HTML_DIR}")
add_custom_target(html DEPENDS ${_SPHINX_INDEX_HTML})
# man target
set(_SPHINX_MAN_DIR "${SHARED_DATA_PATH}/man")
file(MAKE_DIRECTORY ${_SPHINX_MAN_DIR})
set(_SPHINX_MAN "${_SPHINX_MAN_DIR}/promod3.1")
add_custom_command(OUTPUT ${_SPHINX_MAN}
MAIN_DEPENDENCY "${_SPHINX_CONF_PY}"
DEPENDS ${_RST_DEPS} ${_DOC_MODULE_DEPS} COMMAND ${SPHINX_BINARY} -b man -c "${_RST_SOURCE_DIR}"
"${_RST_SOURCE_DIR}" "${_SPHINX_MAN_DIR}")
add_custom_target(man DEPENDS ${_SPHINX_MAN})
# doc target, registered with all
add_custom_target(doc ALL)
add_dependencies(doc html)
add_dependencies(doc man)
# linkcheck target
set(_SPHINX_LINKCHECK_DIR "${CMAKE_CURRENT_BINARY_DIR}/linkcheck")
file(MAKE_DIRECTORY ${_SPHINX_LINKCHECK_DIR})
add_custom_target(linkcheck
COMMAND ${SPHINX_BINARY} -b linkcheck -c "${_RST_SOURCE_DIR}"
"${_RST_SOURCE_DIR}" "${_SPHINX_LINKCHECK_DIR}"
DEPENDS "${_SPHINX_CONF_PY}" ${_RST_DEPS} ${_DOC_MODULE_DEPS})
# register doctest & linkcheck with check
if(NOT DISABLE_DOCTEST)
add_dependencies(check doctest)
endif()
if(NOT DISABLE_LINKCHECK)
add_dependencies(check linkcheck)
endif()
# installing: Since shared data goes to our own sub directory, it is assumed
# save to just copy over whole directories. This saves us from
# keeping track of all output files of a html doc tree
# We install FROM the stage dir tree, since Sphinx will build the
# documentation right there.
# install html documentation
install(DIRECTORY ${_SPHINX_HTML_DIR} DESTINATION "share/promod3")
# install man pages
install(DIRECTORY ${_SPHINX_MAN_DIR} DESTINATION "share/promod3")