Skip to content
Snippets Groups Projects
Commit 52f51c9c authored by Stefan's avatar Stefan
Browse files

Set up build system for sphinx documentation (so far)

parent efd1c798
No related branches found
No related tags found
No related merge requests found
...@@ -621,7 +621,7 @@ macro(pymod) ...@@ -621,7 +621,7 @@ macro(pymod)
# sphinx documentation # sphinx documentation
#----------------------------------------------------------------------------- #-----------------------------------------------------------------------------
if(NOT DISABLE_DOCUMENTATION) if(NOT DISABLE_DOCUMENTATION)
add_doc_dependency(DEP ${_ABS_PY_FILES}) add_doc_dependency(NAME ${_ARG_NAME} DEP ${_ABS_PY_FILES})
add_module_name(MOD ${_ARG_NAME}) add_module_name(MOD ${_ARG_NAME})
endif() endif()
endmacro() endmacro()
...@@ -884,26 +884,30 @@ endmacro() ...@@ -884,26 +884,30 @@ endmacro()
#------------------------------------------------------------------------------- #-------------------------------------------------------------------------------
# Synopsis: # Synopsis:
# add_doc_dependency(DEP dependencies) # add_doc_dependency(NAME module DEP dependencies)
# #
# Description: # Description:
# Add a dependecy for the doc build system. # Add a dependecy for the doc build system.
# DEP - file/ cmake list of files to be added # NAME - name of the module, these dependencies belong to
# DEP - file/ cmake list of files to be added
#------------------------------------------------------------------------------- #-------------------------------------------------------------------------------
macro(add_doc_dependency) macro(add_doc_dependency)
parse_argument_list(_ARG "DEP" "" ${ARGN}) parse_argument_list(_ARG "NAME;DEP" "" ${ARGN})
if (NOT _ARG_NAME)
message(FATAL_ERROR "invalid use of add_doc_dependency(): module name missing")
endif()
if (NOT _ARG_DEP) if (NOT _ARG_DEP)
message(FATAL_ERROR "invalid use of add_doc_dependency(): dependencies missing") message(FATAL_ERROR "invalid use of add_doc_dependency(): dependencies missing")
endif() endif()
if(DEFINED PM3_DOC_DEPS) if(DEFINED PM3_DOC_DEPS_${_ARG_NAME})
set(_DOC_DEPS "${PM3_DOC_DEPS}") set(_DOC_DEPS "${PM3_DOC_DEPS_${_ARG_NAME}}")
else() else()
set(_DOC_DEPS) set(_DOC_DEPS)
endif() endif()
foreach(deps ${_ARG_DEP}) foreach(deps ${_ARG_DEP})
list(APPEND _DOC_DEPS "${deps}") list(APPEND _DOC_DEPS "${deps}")
endforeach() endforeach()
set(PM3_DOC_DEPS "${_DOC_DEPS}" CACHE INTERNAL "" FORCE) set(PM3_DOC_DEPS_${_ARG_NAME} "${_DOC_DEPS}" CACHE INTERNAL "" FORCE)
endmacro() endmacro()
#------------------------------------------------------------------------------- #-------------------------------------------------------------------------------
......
message(STATUS "DOC DEPS ${PM3_DOC_DEPS}") # preparing sphinx build
message(STATUS "MODULES ${PM3_MODULES}") # - 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/...?
# set up commands for the rst source files
# we need to copy index.rst from the source dir, to have everything together in
# the build dir as 'source'; conf.py may stay where it is, may be pulled by '-c'
set(_RST_DEPS)
set(_RST_SOURCE_DIR "${CMAKE_CURRENT_BINARY_DIR}/source")
file(MAKE_DIRECTORY ${_RST_SOURCE_DIR})
set(_SPHINX_INDEX_RST "${_RST_SOURCE_DIR}/index.rst")
add_custom_command(OUTPUT "${_SPHINX_INDEX_RST}"
MAIN_DEPENDENCY "${CMAKE_CURRENT_SOURCE_DIR}/source/index.rst"
COMMAND ${CMAKE_COMMAND} -E copy "${CMAKE_CURRENT_SOURCE_DIR}/source/index.rst" ${_SPHINX_INDEX_RST})
set(_RST_DEPS ${_RST_DEPS} ${_SPHINX_INDEX_RST})
# iterate list of ALL modules registered by pymod()/ add_doc_source()
foreach(mod ${PM3_MODULES}) foreach(mod ${PM3_MODULES})
# 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()
if(DEFINED PM3_RST_${mod}) if(DEFINED PM3_RST_${mod})
message(STATUS "RST:${mod} ${PM3_RST_${mod}}") # this is a list of rst files, of which everyone becomes a Make target
foreach(rst ${PM3_RST_${mod}})
# the list come swith 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})
# 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() endif()
endforeach() endforeach()
# create targets for sphinx # create targets for sphinx
add_custom_command(OUTPUT build/index.html COMMAND touch build/index.html) set(_SPHINX_CONF "${CMAKE_CURRENT_SOURCE_DIR}/source/conf.py")
add_custom_target(html DEPENDS build/index.html) # 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}"
DEPENDS ${_RST_DEPS}
COMMAND ${SPHINX_BINARY} -b html -c "${CMAKE_CURRENT_SOURCE_DIR}/source" "${_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}"
DEPENDS ${_RST_DEPS}
COMMAND ${SPHINX_BINARY} -b man -c "${CMAKE_CURRENT_SOURCE_DIR}/source" "${_RST_SOURCE_DIR}" "${_SPHINX_MAN_DIR}")
add_custom_target(man DEPENDS ${_SPHINX_MAN})
# targets html, man, etc. depend on rst files # doc target, registered with all
# gathered in certain dir add_custom_target(doc ALL DEPENDS html man)
# rst files in certain dir, depend on orginal file (full path), and sources
# can we get a PM3_DOC_DEPS per module?
# for this we would need a modules list
# strategy: # doctest & linkcheck goes into check, once its created
# - create per module rst file list # what about extratcting stuff from code?
# - non doced modules are recognised because they are lacking the rst pendant
# - will be iterated to set up rules n' stuff
# - store dependencies module-rst-file wise
# - pymod knows which module it is, can add dependencies
# - doc stuff needs module name, adds rst to deps
# - if a rst is invoked by two modules: detect and extend dependency list
# - check for redundancy
# - custom_commands on rst files to copy to certain dir
# - depend on individual list of deps
# - html/ man/ etc. depend on index.html/ man page file
# - index.html depends on rst files
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Please register or to comment