mirror of
https://github.com/opencv/opencv.git
synced 2024-12-26 18:58:16 +08:00
269 lines
11 KiB
CMake
269 lines
11 KiB
CMake
#-----------------------
|
|
# CMake file for OpenCV docs
|
|
#-----------------------
|
|
|
|
set(HAVE_DOC_GENERATOR BUILD_DOCS AND (HAVE_SPHINX OR HAVE_DOXYGEN))
|
|
|
|
if(HAVE_DOC_GENERATOR)
|
|
project(opencv_docs)
|
|
# build lists of modules to be documented
|
|
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 BASE_MODULES ${mod})
|
|
else()
|
|
list(APPEND EXTRA_MODULES ${mod})
|
|
endif()
|
|
endforeach()
|
|
ocv_list_sort(BASE_MODULES)
|
|
ocv_list_sort(EXTRA_MODULES)
|
|
set(FIXED_ORDER_MODULES core imgproc imgcodecs videoio highgui video calib3d features2d objdetect ml flann photo stitching)
|
|
list(REMOVE_ITEM BASE_MODULES ${FIXED_ORDER_MODULES})
|
|
set(BASE_MODULES ${FIXED_ORDER_MODULES} ${BASE_MODULES})
|
|
|
|
set(DOC_LIST
|
|
"${OpenCV_SOURCE_DIR}/doc/opencv-logo.png"
|
|
"${OpenCV_SOURCE_DIR}/doc/opencv-logo2.png"
|
|
"${OpenCV_SOURCE_DIR}/doc/opencv-logo-white.png"
|
|
"${OpenCV_SOURCE_DIR}/doc/opencv.ico"
|
|
"${OpenCV_SOURCE_DIR}/doc/pattern.png"
|
|
"${OpenCV_SOURCE_DIR}/doc/acircles_pattern.png")
|
|
set(OPTIONAL_DOC_LIST "")
|
|
endif(HAVE_DOC_GENERATOR)
|
|
|
|
# ========= Sphinx docs =========
|
|
if(BUILD_DOCS AND HAVE_SPHINX)
|
|
if(NOT INSTALL_CREATE_DISTRIB)
|
|
list(APPEND DOC_LIST "${OpenCV_SOURCE_DIR}/doc/haartraining.htm")
|
|
endif()
|
|
|
|
# build lists of documentation files and generate table of contents for reference manual
|
|
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 ${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()
|
|
|
|
configure_file("${OpenCV_SOURCE_DIR}/modules/refman.rst.in" "${DOC_FAKE_ROOT}/modules/refman.rst" @ONLY)
|
|
|
|
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")
|
|
|
|
set(BUILD_PLANTUML "")
|
|
if(PLANTUML)
|
|
set(BUILD_PLANTUML "-tplantuml")
|
|
endif()
|
|
|
|
if(PDFLATEX_COMPILER)
|
|
add_custom_target(docs
|
|
COMMAND ${SPHINX_BUILD} ${BUILD_PLANTUML} -b latex -c "${CMAKE_CURRENT_SOURCE_DIR}" "${DOC_FAKE_ROOT}" .
|
|
COMMAND ${CMAKE_COMMAND} -E copy_if_different ${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty ${CMAKE_CURRENT_BINARY_DIR}
|
|
COMMAND ${PYTHON_DEFAULT_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/patch_refman_latex.py" opencv2refman.tex
|
|
COMMAND ${PYTHON_DEFAULT_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/patch_refman_latex.py" opencv2manager.tex
|
|
COMMAND ${CMAKE_COMMAND} -E echo "Generating opencv2refman.pdf"
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv2refman.tex
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv2refman.tex
|
|
COMMAND ${CMAKE_COMMAND} -E echo "Generating opencv2manager.pdf"
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv2manager.tex
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv2manager.tex
|
|
COMMAND ${CMAKE_COMMAND} -E echo "Generating opencv_user.pdf"
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv_user.tex
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv_user.tex
|
|
COMMAND ${CMAKE_COMMAND} -E echo "Generating opencv_tutorials.pdf"
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv_tutorials.tex
|
|
COMMAND ${PDFLATEX_COMPILER} -interaction=batchmode opencv_tutorials.tex
|
|
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 ${DOC_FAKE_ROOT_FILES}
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
|
COMMENT "Generating the PDF Manuals"
|
|
)
|
|
|
|
LIST(APPEND OPTIONAL_DOC_LIST "${CMAKE_BINARY_DIR}/doc/opencv2refman.pdf" "${CMAKE_BINARY_DIR}/doc/opencv2manager.pdf"
|
|
"${CMAKE_BINARY_DIR}/doc/opencv_user.pdf" "${CMAKE_BINARY_DIR}/doc/opencv_tutorials.pdf" "${CMAKE_BINARY_DIR}/doc/opencv_cheatsheet.pdf")
|
|
|
|
if(ENABLE_SOLUTION_FOLDERS)
|
|
set_target_properties(docs PROPERTIES FOLDER "documentation")
|
|
endif()
|
|
endif()
|
|
|
|
add_custom_target(html_docs
|
|
COMMAND "${SPHINX_BUILD}" ${BUILD_PLANTUML} -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 ${DOC_FAKE_ROOT_FILES}
|
|
WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
|
|
COMMENT "Generating Online Documentation"
|
|
)
|
|
|
|
if(ENABLE_SOLUTION_FOLDERS)
|
|
set_target_properties(html_docs PROPERTIES FOLDER "documentation")
|
|
endif()
|
|
|
|
endif()
|
|
|
|
# ========= Doxygen docs =========
|
|
|
|
if(BUILD_DOCS AND HAVE_DOXYGEN)
|
|
# not documented modules list
|
|
list(APPEND blacklist "ts" "java" "python2" "python3" "world")
|
|
|
|
# gathering headers
|
|
set(paths_include)
|
|
set(paths_doc)
|
|
set(paths_bib)
|
|
set(paths_sample)
|
|
set(paths_tutorial)
|
|
set(refs_main)
|
|
set(refs_extra)
|
|
set(deps)
|
|
foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
|
|
list(FIND blacklist ${m} _pos)
|
|
if(${_pos} EQUAL -1)
|
|
# include folder
|
|
set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
|
|
if(EXISTS "${header_dir}")
|
|
list(APPEND paths_include "${header_dir}")
|
|
list(APPEND deps ${header_dir})
|
|
endif()
|
|
# doc folder
|
|
set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
|
|
if(EXISTS "${docs_dir}")
|
|
list(APPEND paths_doc "${docs_dir}")
|
|
list(APPEND deps ${docs_dir})
|
|
endif()
|
|
# sample folder
|
|
set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
|
|
if(EXISTS "${sample_dir}")
|
|
list(APPEND paths_sample "${sample_dir}")
|
|
list(APPEND deps ${sample_dir})
|
|
endif()
|
|
# tutorial folder
|
|
set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
|
|
if(EXISTS "${tutorial_dir}")
|
|
list(APPEND paths_tutorial "${tutorial_dir}")
|
|
list(APPEND deps ${tutorial_dir})
|
|
endif()
|
|
# BiBTeX file
|
|
set(bib_file "${docs_dir}/${m}.bib")
|
|
if(EXISTS "${bib_file}")
|
|
set(paths_bib "${paths_bib} ${bib_file}")
|
|
list(APPEND deps ${bib_file})
|
|
endif()
|
|
# Reference entry
|
|
# set(one_ref "@ref ${m} | ${m}\n")
|
|
set(one_ref "\t- ${m}. @ref ${m}\n")
|
|
list(FIND EXTRA_MODULES ${m} _pos)
|
|
if(${_pos} EQUAL -1)
|
|
set(refs_main "${refs_main}${one_ref}")
|
|
else()
|
|
set(refs_extra "${refs_extra}${one_ref}")
|
|
endif()
|
|
endif()
|
|
endforeach()
|
|
|
|
# fix references
|
|
# set(ref_header "Module name | Folder\n----------- | ------")
|
|
# if(refs_main)
|
|
# set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
|
|
# endif()
|
|
# if(refs_extra)
|
|
# set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
|
|
# endif()
|
|
if(refs_main)
|
|
set(refs_main "- Main modules:\n${refs_main}")
|
|
endif()
|
|
if(refs_extra)
|
|
set(refs_extra "- Extra modules:\n${refs_extra}")
|
|
endif()
|
|
|
|
# additional config
|
|
set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
|
|
set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
|
|
set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
|
|
set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
|
|
set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
|
|
set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
|
|
set(user_guide_path "${CMAKE_CURRENT_SOURCE_DIR}/user_guide")
|
|
set(example_path "${CMAKE_SOURCE_DIR}/samples")
|
|
|
|
# set export variables
|
|
string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${faqfile} ; ${paths_include} ; ${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${user_guide_path} ; ${paths_tutorial}")
|
|
string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${user_guide_path} ; ${paths_tutorial}")
|
|
# TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
|
|
string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH "${example_path} ; ${paths_doc} ; ${paths_sample}")
|
|
set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
|
|
set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
|
|
set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
|
|
set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
|
|
set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
|
|
|
|
# writing file
|
|
configure_file(Doxyfile.in ${doxyfile} @ONLY)
|
|
configure_file(root.markdown.in ${rootfile} @ONLY)
|
|
configure_file(mymath.sty "${CMAKE_DOXYGEN_OUTPUT_PATH}/html/mymath.sty" @ONLY)
|
|
configure_file(mymath.sty "${CMAKE_DOXYGEN_OUTPUT_PATH}/latex/mymath.sty" @ONLY)
|
|
|
|
# TODO: do not store downloadable samples, but give github link instead
|
|
add_custom_target(doxygen
|
|
COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_SOURCE_DIR}/samples" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html/samples"
|
|
COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html"
|
|
COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html"
|
|
COMMAND ${DOXYGEN_BUILD} ${doxyfile}
|
|
DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps}
|
|
)
|
|
endif()
|
|
|
|
if(HAVE_DOC_GENERATOR)
|
|
# installation
|
|
foreach(f ${DOC_LIST})
|
|
install(FILES "${f}" DESTINATION "${OPENCV_DOC_INSTALL_PATH}" COMPONENT docs)
|
|
endforeach()
|
|
foreach(f ${OPTIONAL_DOC_LIST})
|
|
install(FILES "${f}" DESTINATION "${OPENCV_DOC_INSTALL_PATH}" OPTIONAL COMPONENT docs)
|
|
endforeach()
|
|
endif(HAVE_DOC_GENERATOR)
|