CMakeLists.txt

# 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
users.rst
buildsystem.rst
contributing.rst
)


# set up commands/ vars/ ... for the rst source files
set(_RST_DEPS)
set(_DOC_MODULE_DEPS)
set(_RST_SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/source")
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_VERSION="${PYTHON_VERSION}"
                            OST_PYMOD_PATH="${OST_PYMOD_PATH}"
                            OST_DOC_URL="${OST_DOC_URL}"
                            LIB_DIR="${LIB_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)
# 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()
# 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)

# doctest target, one is enough for all
set(_SPHINX_DOCTEST_DIR "${CMAKE_CURRENT_BINARY_DIR}/doctest")
file(MAKE_DIRECTORY ${_SPHINX_DOCTEST_DIR})
add_custom_target(doctest
                  COMMAND ${SPHINX_BINARY} -b doctest -c "${_RST_SOURCE_DIR}"
                                   "${_RST_SOURCE_DIR}" "${_SPHINX_DOCTEST_DIR}"
                  DEPENDS "${_SPHINX_CONF_PY}" ${_RST_DEPS} ${_DOC_MODULE_DEPS}
                                         ${PM3_PYMODULES} ${PM3_UNIT_TEST_DATA})

# 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")