mirror of
https://github.com/eclipse/upm.git
synced 2025-11-04 09:05:34 +03:00
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>
This commit is contained in:
Noel Eck
@@ -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</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
|
||||
|
||||
Reference in New Issue
Block a user