Reworked documentation building to work with extra modules.
The main problem with extra modules is that they're located outside of the OpenCV root, while Sphinx requires that all documents are within the documentation root. To circumvent this, we create a "fake root" and copy all documentation (as well as all files that it depends on) there. It's a bit messy, but what can you do. As a bonus, this eliminates the need to generate modules/refman.rst inside the source tree.
This commit is contained in:
Roman Donchenko
parent
a81efdbb25
commit
3314bc94b6
1
.gitignore
vendored
1
.gitignore
vendored
@ -4,6 +4,5 @@
|
||||
.*.swp
|
||||
.DS_Store
|
||||
.sw[a-z]
|
||||
/modules/refman.rst
|
||||
tags
|
||||
tegra/
|
||||
|
||||
@ -2,9 +2,6 @@
|
||||
# CMake file for OpenCV docs
|
||||
#
|
||||
|
||||
file(GLOB FILES_TEX *.tex *.sty *.bib)
|
||||
file(GLOB FILES_TEX_PICS pics/*.png pics/*.jpg)
|
||||
|
||||
if(BUILD_DOCS AND HAVE_SPHINX)
|
||||
|
||||
project(opencv_docs)
|
||||
@ -23,59 +20,84 @@ if(BUILD_DOCS AND HAVE_SPHINX)
|
||||
set(OPTIONAL_DOC_LIST "")
|
||||
|
||||
|
||||
set(OPENCV2_BASE_MODULES core imgproc highgui video calib3d features2d objdetect ml flann gpu photo stitching nonfree contrib legacy)
|
||||
|
||||
# build lists of modules to be documented
|
||||
set(OPENCV2_MODULES "")
|
||||
set(OPENCV_MODULES "")
|
||||
set(BASE_MODULES "")
|
||||
set(EXTRA_MODULES "")
|
||||
|
||||
foreach(mod ${OPENCV_MODULES_BUILD} ${OPENCV_MODULES_DISABLED_USER} ${OPENCV_MODULES_DISABLED_AUTO} ${OPENCV_MODULES_DISABLED_FORCE})
|
||||
string(REGEX REPLACE "^opencv_" "" mod "${mod}")
|
||||
if("${OPENCV_MODULE_opencv_${mod}_LOCATION}" STREQUAL "${OpenCV_SOURCE_DIR}/modules/${mod}")
|
||||
list(APPEND OPENCV2_MODULES ${mod})
|
||||
list(APPEND BASE_MODULES ${mod})
|
||||
else()
|
||||
list(APPEND OPENCV_MODULES ${mod})
|
||||
list(APPEND EXTRA_MODULES ${mod})
|
||||
endif()
|
||||
endforeach()
|
||||
list(REMOVE_ITEM OPENCV2_MODULES ${OPENCV2_BASE_MODULES})
|
||||
ocv_list_sort(OPENCV2_MODULES)
|
||||
ocv_list_sort(OPENCV_MODULES)
|
||||
|
||||
set(FIXED_ORDER_MODULES core imgproc highgui video calib3d features2d objdetect ml flann gpu photo stitching nonfree contrib legacy)
|
||||
|
||||
list(REMOVE_ITEM BASE_MODULES ${FIXED_ORDER_MODULES})
|
||||
|
||||
ocv_list_sort(BASE_MODULES)
|
||||
ocv_list_sort(EXTRA_MODULES)
|
||||
|
||||
set(BASE_MODULES ${FIXED_ORDER_MODULES} ${BASE_MODULES})
|
||||
|
||||
# build lists of documentation files and generate table of contents for reference manual
|
||||
set(OPENCV_FILES_REF "")
|
||||
set(OPENCV_FILES_REF_PICT "")
|
||||
|
||||
set(DOC_FAKE_ROOT "${CMAKE_CURRENT_BINARY_DIR}/fake-root")
|
||||
set(DOC_FAKE_ROOT_FILES "")
|
||||
|
||||
function(ocv_doc_add_file_to_fake_root source destination)
|
||||
add_custom_command(
|
||||
OUTPUT "${DOC_FAKE_ROOT}/${destination}"
|
||||
COMMAND "${CMAKE_COMMAND}" -E copy "${source}" "${DOC_FAKE_ROOT}/${destination}"
|
||||
DEPENDS "${source}"
|
||||
COMMENT "Copying ${destination} to fake root..."
|
||||
VERBATIM
|
||||
)
|
||||
list(APPEND DOC_FAKE_ROOT_FILES "${DOC_FAKE_ROOT}/${destination}")
|
||||
set(DOC_FAKE_ROOT_FILES "${DOC_FAKE_ROOT_FILES}" PARENT_SCOPE)
|
||||
endfunction()
|
||||
|
||||
function(ocv_doc_add_to_fake_root source)
|
||||
if(ARGC GREATER 1)
|
||||
set(destination "${ARGV1}")
|
||||
else()
|
||||
file(RELATIVE_PATH destination "${OpenCV_SOURCE_DIR}" "${source}")
|
||||
endif()
|
||||
|
||||
if(IS_DIRECTORY "${source}")
|
||||
file(GLOB_RECURSE files RELATIVE "${source}" "${source}/*")
|
||||
|
||||
foreach(file ${files})
|
||||
ocv_doc_add_file_to_fake_root("${source}/${file}" "${destination}/${file}")
|
||||
endforeach()
|
||||
else()
|
||||
ocv_doc_add_file_to_fake_root("${source}" "${destination}")
|
||||
endif()
|
||||
|
||||
set(DOC_FAKE_ROOT_FILES "${DOC_FAKE_ROOT_FILES}" PARENT_SCOPE)
|
||||
endfunction()
|
||||
|
||||
set(OPENCV_REFMAN_TOC "")
|
||||
|
||||
foreach(mod ${OPENCV2_BASE_MODULES} ${OPENCV2_MODULES} ${OPENCV_MODULES})
|
||||
file(GLOB_RECURSE _OPENCV_FILES_REF "${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc/*.rst")
|
||||
file(GLOB_RECURSE _OPENCV_FILES_REF_PICT "${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc/*.png" "${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc/*.jpg")
|
||||
list(APPEND OPENCV_FILES_REF ${_OPENCV_FILES_REF})
|
||||
list(APPEND OPENCV_FILES_REF_PICT ${_OPENCV_FILES_REF_PICT})
|
||||
|
||||
set(toc_file "${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc/${mod}.rst")
|
||||
if(EXISTS "${toc_file}")
|
||||
file(RELATIVE_PATH toc_file "${OpenCV_SOURCE_DIR}/modules" "${toc_file}")
|
||||
set(OPENCV_REFMAN_TOC "${OPENCV_REFMAN_TOC} ${toc_file}\n")
|
||||
foreach(mod ${BASE_MODULES} ${EXTRA_MODULES})
|
||||
if(EXISTS "${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc/${mod}.rst")
|
||||
ocv_doc_add_to_fake_root("${OPENCV_MODULE_opencv_${mod}_LOCATION}/doc" modules/${mod}/doc)
|
||||
set(OPENCV_REFMAN_TOC "${OPENCV_REFMAN_TOC} ${mod}/doc/${mod}.rst\n")
|
||||
endif()
|
||||
endforeach()
|
||||
|
||||
file(GLOB_RECURSE _OPENCV_FILES_REF "${OpenCV_SOURCE_DIR}/platforms/android/service/doc/*.rst")
|
||||
file(GLOB_RECURSE _OPENCV_FILES_REF_PICT "${OpenCV_SOURCE_DIR}/platforms/android/service/doc/*.png" "${OpenCV_SOURCE_DIR}/platforms/android/service/doc/*.jpg")
|
||||
list(APPEND OPENCV_FILES_REF ${_OPENCV_FILES_REF})
|
||||
list(APPEND OPENCV_FILES_REF_PICT ${_OPENCV_FILES_REF_PICT})
|
||||
configure_file("${OpenCV_SOURCE_DIR}/modules/refman.rst.in" "${DOC_FAKE_ROOT}/modules/refman.rst" @ONLY)
|
||||
|
||||
configure_file("${OpenCV_SOURCE_DIR}/modules/refman.rst.in" "${OpenCV_SOURCE_DIR}/modules/refman.rst" IMMEDIATE @ONLY)
|
||||
|
||||
file(GLOB_RECURSE OPENCV_FILES_UG user_guide/*.rst)
|
||||
file(GLOB_RECURSE OPENCV_FILES_TUT tutorials/*.rst)
|
||||
file(GLOB_RECURSE OPENCV_FILES_TUT_PICT tutorials/*.png tutorials/*.jpg)
|
||||
|
||||
set(OPENCV_DOC_DEPS conf.py ${OPENCV_FILES_REF} ${OPENCV_FILES_REF_PICT}
|
||||
${OPENCV_FILES_UG} ${OPENCV_FILES_TUT} ${OPENCV_FILES_TUT_PICT})
|
||||
ocv_doc_add_to_fake_root("${OpenCV_SOURCE_DIR}/index.rst")
|
||||
ocv_doc_add_to_fake_root("${OpenCV_SOURCE_DIR}/doc")
|
||||
ocv_doc_add_to_fake_root("${OpenCV_SOURCE_DIR}/platforms/android")
|
||||
ocv_doc_add_to_fake_root("${OpenCV_SOURCE_DIR}/samples")
|
||||
|
||||
if(PDFLATEX_COMPILER)
|
||||
add_custom_target(docs
|
||||
COMMAND ${SPHINX_BUILD} -b latex -c ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/.. .
|
||||
COMMAND ${SPHINX_BUILD} -b latex -c "${CMAKE_CURRENT_SOURCE_DIR}" "${DOC_FAKE_ROOT}" .
|
||||
COMMAND ${CMAKE_COMMAND} -E copy_directory ${CMAKE_CURRENT_SOURCE_DIR}/pics ${CMAKE_CURRENT_BINARY_DIR}/doc/opencv1/pics
|
||||
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMAND ${PYTHON_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/patch_refman_latex.py" opencv2refman.tex
|
||||
@ -95,7 +117,7 @@ if(BUILD_DOCS AND HAVE_SPHINX)
|
||||
COMMAND ${CMAKE_COMMAND} -E echo "Generating opencv_cheatsheet.pdf"
|
||||
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode "${CMAKE_CURRENT_SOURCE_DIR}/opencv_cheatsheet.tex"
|
||||
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode "${CMAKE_CURRENT_SOURCE_DIR}/opencv_cheatsheet.tex"
|
||||
DEPENDS ${OPENCV_DOC_DEPS}
|
||||
DEPENDS ${DOC_FAKE_ROOT_FILES}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating the PDF Manuals"
|
||||
)
|
||||
@ -109,9 +131,9 @@ if(BUILD_DOCS AND HAVE_SPHINX)
|
||||
endif()
|
||||
|
||||
add_custom_target(html_docs
|
||||
COMMAND ${SPHINX_BUILD} -b html -c ${CMAKE_CURRENT_SOURCE_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/.. ./_html
|
||||
COMMAND "${SPHINX_BUILD}" -b html -c "${CMAKE_CURRENT_SOURCE_DIR}" "${DOC_FAKE_ROOT}" ./_html
|
||||
COMMAND ${CMAKE_COMMAND} -E copy ${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty ${CMAKE_CURRENT_BINARY_DIR}
|
||||
DEPENDS ${OPENCV_DOC_DEPS}
|
||||
DEPENDS ${DOC_FAKE_ROOT_FILES}
|
||||
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
||||
COMMENT "Generating Online Documentation"
|
||||
)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user