diff --git a/CMakeLists.txt b/CMakeLists.txt index 89b0ed31..f1ad5830 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -275,37 +275,36 @@ else() set (C_EXTENSIONS OFF) endif() -# The doc target depends on each sensor target +# The doc target depends on the C/C++ source and all libraries # # doc +# ├──> src +# ├──> include # ├──> libupm_sensor0 # ├──> libupm_sensor1 -# ├──> libupm_sensor2 +# ├──> ... # └──> libupm_sensor_n # # The pydoc target builds documentation with sphinx via inspection by loading -# each python module. Those modules must include the CXX documentation via +# each python2 module. Those modules must include the CXX documentation via # a monolithic swig file generated by doxy2swig # # pydoc # └──> _pyupm_sensor0_python2 -# ├──────> libupm_sensor0 -# └──────> doxy2swig +# ├──> libupm_sensor0 +# └──> doxy2swig # # The doxy2swig target is dependent upon the doc target IF BUILDDOC=ON, -# otherwise doxy2swig uses an empty file. Doxy2swig also depends on each -# sensor target # # doxy2swig -# ├──> BUILDDOC=ON───> doc -# └──> libupm_sensor0 +# └──> BUILDDOC=ON───> doc # # The jsdoc target builds js documentation via yuidoc and only requires # the doc target # # jsdoc ─> doc # -if (BUILDDOC) +function (CreateDocumentationTargets) # Add a target to generate API documentation with Doxygen find_package (Doxygen 1.8 REQUIRED) if (DOXYGEN_FOUND AND DOXYGEN_VERSION VERSION_GREATER "1.8") @@ -317,12 +316,17 @@ if (BUILDDOC) foreach(PNG_FILE ${PNG_FILES}) configure_file(${CMAKE_CURRENT_SOURCE_DIR}/docs/${PNG_FILE} ${CMAKE_CURRENT_BINARY_DIR}/html/docs/${PNG_FILE} COPYONLY) endforeach() - add_custom_target (doc - ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile + + # Custom command to run doxygen (note depends on ALL UPM C++ targets) + add_custom_command ( + OUTPUT ${CMAKE_BINARY_DIR}/xml/index.xml + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile ${UPM_TARGETS_CXX} + COMMAND ${DOXYGEN_EXECUTABLE} ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile COMMAND tar -czf html/xml.tar.gz -C xml . WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating C/C++ API documentation with Doxygen" VERBATIM - ) + COMMENT "Generating C/C++ API documentation with Doxygen" + VERBATIM) + add_custom_target(doc DEPENDS ${CMAKE_BINARY_DIR}/xml/index.xml) else () message (SEND_ERROR "ERROR - Failed to find a compatible version of Doxygen. API doc will not be generated") endif (DOXYGEN_FOUND AND DOXYGEN_VERSION VERSION_GREATER "1.8") @@ -335,11 +339,28 @@ if (BUILDDOC) # the sphinx tools, explicitly run from the python2 interpreter (tested with the sphinx # 1.3.6 python2 and python3 modules). if(BUILDSWIGPYTHON) + # Generate python module documentation from doxygen collateral + # + # doxygen index.xml -> doxy2swig.py -> pyupm_doxy2swig.i + add_custom_command ( + OUTPUT ${CMAKE_BINARY_DIR}/src/pyupm_doxy2swig.i + COMMAND ${PYTHON2_EXECUTABLE} ${CMAKE_SOURCE_DIR}/src/doxy2swig.py + ${CMAKE_BINARY_DIR}/xml/index.xml --quiet + ${CMAKE_BINARY_DIR}/src/pyupm_doxy2swig.i + COMMENT "Generating pyupm_doxy2swig.i from Doxygen output for use by SWIG" + DEPENDS doc + VERBATIM) + add_custom_target(pyupm_doxy2swig DEPENDS ${CMAKE_BINARY_DIR}/src/pyupm_doxy2swig.i) + foreach (_python2_target ${UPM_TARGETS_PYTHON2}) + add_dependencies(${_python2_target} pyupm_doxy2swig) + endforeach() + find_package (Sphinx 1.3 REQUIRED) if (SPHINX_FOUND AND SPHINX_VERSION VERSION_GREATER "1.3") configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/conf.py.in ${CMAKE_CURRENT_BINARY_DIR}/pydoc/conf.py @ONLY) configure_file (${CMAKE_CURRENT_SOURCE_DIR}/doxy/index.rst ${CMAKE_CURRENT_BINARY_DIR}/pydoc/index.rst COPYONLY) - add_custom_target (pydoc ALL + add_custom_command ( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/pydoc.stamp COMMAND rm -r -f ${CMAKE_BINARY_DIR}/pyupm && mkdir -p ${CMAKE_BINARY_DIR}/pyupm COMMAND find ${CMAKE_BINARY_DIR}/src -path "*python${MIN_VER_PYTHON2}/_pyupm_*.so" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \; COMMAND find ${CMAKE_BINARY_DIR}/src -path "*python${MIN_VER_PYTHON2}/pyupm_*.py" -exec cp {} ${CMAKE_BINARY_DIR}/pyupm \; @@ -348,10 +369,12 @@ if (BUILDDOC) COMMAND ${PYTHON2_EXECUTABLE} ${SPHINX_EXECUTABLE} -b html pydoc html/python COMMAND sed -i.bak s|\">pyupm_|\">|g html/python/index.html html/python/modules.html COMMAND sed -i.bak s|[[:space:]][mM]odule||g html/python/index.html html/python/modules.html - DEPENDS doc + COMMAND cmake -E touch ${CMAKE_CURRENT_BINARY_DIR}/pydoc.stamp WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating Python API documentation with Sphinx" VERBATIM - ) + COMMENT "Generating Python API documentation with Sphinx" + DEPENDS doc ${UPM_TARGETS_PYTHON2} + VERBATIM) + add_custom_target(pydoc DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/pydoc.stamp) else () message (SEND_ERROR "ERROR - Failed to find a compatible version of Sphinx. Python API doc will not be generated") endif () @@ -361,19 +384,22 @@ if (BUILDDOC) if(BUILDSWIGNODE) find_package (Yuidoc 0.10 REQUIRED) if (YUIDOC_FOUND AND YUIDOC_VERSION VERSION_GREATER "0.10") - add_custom_target (jsdoc ALL + add_custom_command ( + OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/jsdoc/jsdoc.stamp COMMAND ${CMAKE_SOURCE_DIR}/doxy/doxygen2jsdoc/docgen.js -m upm -i xml -o jsdoc -t ${CMAKE_CURRENT_SOURCE_DIR}/src -g ../../ COMMAND ${YUIDOC_EXECUTABLE} -C --no-sort --helpers ${CMAKE_SOURCE_DIR}/doxy/node/generators/yuidoc/helper.js --themedir ${CMAKE_SOURCE_DIR}/doxy/node/generators/yuidoc/tmpl -o html/node jsdoc/yuidoc/upm COMMAND ${CMAKE_SOURCE_DIR}/doxy/doxygen2jsdoc/tolower.js -i html/node - DEPENDS doc + COMMAND cmake -E touch ${CMAKE_CURRENT_BINARY_DIR}/jsdoc/jsdoc.stamp WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR} - COMMENT "Generating Javascript API documentation with Yuidoc" VERBATIM - ) + COMMENT "Generating Javascript API documentation with Yuidoc" + DEPENDS doc + VERBATIM) + add_custom_target(jsdoc DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/jsdoc/jsdoc.stamp) else () message (SEND_ERROR "ERROR - Failed to find a compatible version of Yuidoc. Node.js API doc will not be generated") endif () endif(BUILDSWIGNODE) -endif (BUILDDOC) +endfunction() if (IPK) # Get target package arch from Yocto ADT sysroot if set or host OS, mapping to Ubuntu name if necessary @@ -455,6 +481,11 @@ if (BUILDTESTS) add_subdirectory (tests) endif() +# Setup documentation AFTER all source targets have been added +if (BUILDDOC) + CreateDocumentationTargets() +endif() + # Install C headers install(DIRECTORY include/ DESTINATION include/upm COMPONENT ${CMAKE_PROJECT_NAME}-dev diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 0d28d5c2..b592b92f 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -326,11 +326,11 @@ macro(_upm_swig_python) # Add C++ comments to ALL python modules (requires doc build) if (BUILDDOC) - # Python module depends on doxy2swig .i file generated from the monolithic doxygen xml file - add_dependencies(${python_wrapper_target} pyupm_doxy2swig ) - - # The pydoc target depends on EACH python module - add_dependencies(pydoc ${python_wrapper_target}) + # The python documentation generated with Sphinx only uses python2 + if (PYTHON_VERSION_MAJOR VERSION_EQUAL 2) + # Python module depends on doxy2swig .i file generated from the monolithic doxygen xml file + add_dependencies(${python_wrapper_target} pyupm_doxy2swig) + endif() endif (BUILDDOC) # Python collateral names will be the same for python2/3 w/different library dirs @@ -861,21 +861,6 @@ if (BUILDSWIGPYTHON) endif(PYTHON3LIBS_FOUND) endif (BUILDSWIGPYTHON) -# Generate python module documentation from doxygen collateral -if (BUILDDOC AND BUILDSWIGPYTHON) - # doxy2swig the doxygen output - add_custom_target (pyupm_doxy2swig ALL - COMMAND ${PYTHON2_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/doxy2swig.py - ${CMAKE_BINARY_DIR}/xml/index.xml --quiet - ${CMAKE_CURRENT_BINARY_DIR}/pyupm_doxy2swig.i - DEPENDS doc) -# BUILDDOC not set but still building python modules, generate an empty -# pyupm_doxy2swig.i file (overwriting if necessary) -elseif (BUILDSWIGPYTHON) - message (STATUS "BUILDDOC=${BUILDDOC}, python modules will not contain cxx documentation") - file (WRITE ${CMAKE_CURRENT_BINARY_DIR}/pyupm_doxy2swig.i "// Empty doxy2swig stub") -endif (BUILDDOC AND BUILDSWIGPYTHON) - # Provide a cached variable to groups of targets set(UPM_TARGETS_C "" CACHE INTERNAL "List of C target names") set(UPM_TARGETS_CXX "" CACHE INTERNAL "List of CXX target names") @@ -925,3 +910,7 @@ _gen_pkg_config_per_target(CXX ${UPM_TARGETS_CXX}) if (BUILDSWIGJAVA) _gen_pom_per_target(${UPM_TARGETS_CXX}) endif (BUILDSWIGJAVA) + +# Available to the top-level CMakeLists.txt +set (UPM_TARGETS_CXX ${UPM_TARGETS_CXX} PARENT_SCOPE) +set (UPM_TARGETS_PYTHON2 ${UPM_TARGETS_PYTHON2} PARENT_SCOPE) diff --git a/src/common_top.i b/src/common_top.i index 41d5991f..f21496f0 100644 --- a/src/common_top.i +++ b/src/common_top.i @@ -50,6 +50,6 @@ void cleanUp(); * output during doc build. This file is used by swig to provide native * python module documentation. */ -#if SWIGPYTHON +#if defined(SWIGPYTHON) && defined(BUILDDOC) %include "pyupm_doxy2swig.i" #endif