docs: Updated doc dependencies for all languages

This commit changes how the UPM doc targets build.  The doc targets no
longer rebuild each time.

    * doc (doxygen) target depends only on C/C++ source
    * jsdoc (yuidoc) depends on doc and a stamp file
    * pydoc (sphinx) depends on the output index.xml from doc
    * pyupm_doxy2swig depends on python2 python extensions

Signed-off-by: Noel Eck <noel.eck@intel.com>

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
+#        ├──> libupm_sensor0
-#        └──────> doxy2swig
+#        └──> 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
+#  └──> BUILDDOC=ON───> doc
-#  └──> libupm_sensor0
 #
 # 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</a>|</a>|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

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
+    # The python documentation generated with Sphinx only uses python2
-    add_dependencies(${python_wrapper_target} pyupm_doxy2swig )
+    if (PYTHON_VERSION_MAJOR VERSION_EQUAL 2)
-
+      # Python module depends on doxy2swig .i file generated from the monolithic doxygen xml file
-    # The pydoc target depends on EACH python module
+      add_dependencies(${python_wrapper_target} pyupm_doxy2swig)
-    add_dependencies(pydoc ${python_wrapper_target})
+    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)

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