1 #-----------------------
2 # CMake file for OpenCV docs
3 #-----------------------
5 if(BUILD_DOCS AND DOXYGEN_FOUND)
6 set(HAVE_DOC_GENERATOR TRUE)
8 set(HAVE_DOC_GENERATOR FALSE)
11 if(HAVE_DOC_GENERATOR)
13 # build lists of modules to be documented
17 foreach(mod ${OPENCV_MODULES_BUILD} ${OPENCV_MODULES_DISABLED_USER} ${OPENCV_MODULES_DISABLED_AUTO} ${OPENCV_MODULES_DISABLED_FORCE})
18 string(REGEX REPLACE "^opencv_" "" mod "${mod}")
19 if("${OPENCV_MODULE_opencv_${mod}_LOCATION}" STREQUAL "${OpenCV_SOURCE_DIR}/modules/${mod}")
20 list(APPEND BASE_MODULES ${mod})
22 list(APPEND EXTRA_MODULES ${mod})
25 ocv_list_sort(BASE_MODULES)
26 ocv_list_sort(EXTRA_MODULES)
27 set(FIXED_ORDER_MODULES core imgproc imgcodecs videoio highgui video calib3d features2d objdetect dnn ml flann photo stitching)
28 list(REMOVE_ITEM BASE_MODULES ${FIXED_ORDER_MODULES})
29 set(BASE_MODULES ${FIXED_ORDER_MODULES} ${BASE_MODULES})
30 endif(HAVE_DOC_GENERATOR)
32 # ========= Doxygen docs =========
34 if(BUILD_DOCS AND DOXYGEN_FOUND)
35 # not documented modules list
36 list(APPEND blacklist "ts" "java_bindings_generator" "java" "python_bindings_generator" "python2" "python3" "js" "world")
37 unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
38 unset(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT)
40 set(OPENCV_MATHJAX_RELPATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0" CACHE STRING "URI to a MathJax installation")
48 set(paths_hal_interface)
52 foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
53 list(FIND blacklist ${m} _pos)
56 set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
57 if(EXISTS "${header_dir}")
58 list(APPEND paths_include "${header_dir}")
59 list(APPEND deps ${header_dir})
62 set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
63 if(EXISTS "${docs_dir}")
64 list(APPEND paths_doc "${docs_dir}")
65 list(APPEND deps ${docs_dir})
68 set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
69 if(EXISTS "${sample_dir}")
70 list(APPEND paths_sample "${sample_dir}")
71 list(APPEND deps ${sample_dir})
74 set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
75 if(EXISTS "${tutorial_dir}")
76 list(APPEND paths_tutorial "${tutorial_dir}")
77 list(APPEND deps ${tutorial_dir})
79 # tutorial reference entry
80 file(GLOB tutorials RELATIVE "${OPENCV_MODULE_opencv_${m}_LOCATION}" "${tutorial_dir}/*.markdown")
81 foreach (t ${tutorials})
82 if (NOT DEFINED CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
83 set(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT "- @ref tutorial_contrib_root")
84 set(tutorial_contrib_root "${CMAKE_CURRENT_BINARY_DIR}/contrib_tutorials.markdown")
85 file(WRITE "${tutorial_contrib_root}"
86 "Tutorials for contrib modules {#tutorial_contrib_root}\n"
87 "=============================\n")
89 file(STRINGS "${OPENCV_MODULE_opencv_${m}_LOCATION}/${t}" tutorial_id LIMIT_COUNT 1 REGEX ".*{#[^}]+}")
90 string(REGEX REPLACE ".*{#([^}]+)}" "\\1" tutorial_id "${tutorial_id}")
91 file(APPEND "${tutorial_contrib_root}" "- ${m}. @subpage ${tutorial_id}\n")
94 # HAL replacement file
95 set(replacement_header "${OPENCV_MODULE_opencv_${m}_LOCATION}/src/hal_replacement.hpp")
96 if(EXISTS "${replacement_header}")
97 list(APPEND paths_hal_interface "${replacement_header}")
101 set(bib_file "${docs_dir}/${m}.bib")
102 if(EXISTS "${bib_file}")
103 set(paths_bib "${paths_bib} ${bib_file}")
104 list(APPEND deps ${bib_file})
107 set(one_ref "\t- ${m}. @ref ${m}\n")
108 list(FIND EXTRA_MODULES ${m} _pos)
110 set(refs_main "${refs_main}${one_ref}")
112 set(refs_extra "${refs_extra}${one_ref}")
118 # set(ref_header "Module name | Folder\n----------- | ------")
120 # set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
123 # set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
126 set(refs_main "- Main modules:\n${refs_main}")
129 set(refs_extra "- Extra modules:\n${refs_extra}")
133 set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
134 set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
135 set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
136 set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
137 set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
138 set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
139 set(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT "- @ref tutorial_js_root")
140 set(tutorial_js_path "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials")
141 set(example_path "${CMAKE_SOURCE_DIR}/samples")
143 # set export variables
144 string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${faqfile} ; ${paths_include} ; ${paths_hal_interface} ; ${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial} ; ${tutorial_contrib_root}")
145 string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial}")
146 # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
147 string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH "${example_path} ; ${paths_doc} ; ${paths_sample}")
148 set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
149 set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
150 set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
151 set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
152 set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
153 if (CMAKE_DOXYGEN_GENERATE_QHP)
154 set(CMAKE_DOXYGEN_GENERATE_QHP "YES")
156 set(CMAKE_DOXYGEN_GENERATE_QHP "NO")
159 list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/opencv.ico")
160 list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
161 list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
162 list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
163 list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
164 string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
167 configure_file(Doxyfile.in ${doxyfile} @ONLY)
168 configure_file(root.markdown.in ${rootfile} @ONLY)
171 set(opencv_tutorial_html_dir "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html")
172 set(js_tutorials_assets_dir "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials/js_assets")
173 set(js_tutorials_assets_deps "")
175 # make sure the build directory exists
176 file(MAKE_DIRECTORY "${opencv_tutorial_html_dir}")
178 # gather and copy specific files for js tutorials
179 file(GLOB_RECURSE js_assets "${js_tutorials_assets_dir}/*")
180 ocv_list_filterout(js_assets "\\\\.eslintrc.json")
181 list(APPEND js_assets "${OpenCV_SOURCE_DIR}/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.mp4")
184 set(ocv_js_dir "${CMAKE_BINARY_DIR}/bin")
185 set(ocv_js "opencv.js")
186 list(APPEND js_assets "${ocv_js_dir}/${ocv_js}")
187 elseif(DEFINED OPENCV_JS_LOCATION)
188 list(APPEND js_assets "${OPENCV_JS_LOCATION}")
191 # copy haar cascade files
192 set(haar_cascade_files "")
193 set(data_harrcascades_path "${OpenCV_SOURCE_DIR}/data/haarcascades/")
194 list(APPEND js_tutorials_assets_deps "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
195 list(APPEND js_assets "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
197 foreach(f ${js_assets})
198 get_filename_component(fname "${f}" NAME)
199 add_custom_command(OUTPUT "${opencv_tutorial_html_dir}/${fname}"
200 COMMAND ${CMAKE_COMMAND} -E copy_if_different "${f}" "${opencv_tutorial_html_dir}/${fname}"
202 COMMENT "Copying ${fname}"
204 list(APPEND js_tutorials_assets_deps "${f}" "${opencv_tutorial_html_dir}/${fname}")
209 COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
210 DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps} ${js_tutorials_assets_deps}
211 COMMENT "Generate Doxygen documentation"
214 install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
215 DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
216 COMPONENT "docs" OPTIONAL
219 if(NOT DEFINED HAVE_PYTHON_BS4 AND PYTHON_DEFAULT_EXECUTABLE)
220 # Documentation post-processing tool requires BuautifulSoup Python package
221 execute_process(COMMAND "${PYTHON_DEFAULT_EXECUTABLE}" -c "import bs4; from bs4 import BeautifulSoup; print(bs4.__version__)"
222 RESULT_VARIABLE _result
223 OUTPUT_VARIABLE _bs4_version
224 OUTPUT_STRIP_TRAILING_WHITESPACE)
226 if(NOT _result EQUAL 0)
227 set(HAVE_PYTHON_BS4 0 CACHE INTERNAL "")
229 message(STATUS "Python BeautifulSoup (bs4) version: ${_bs4_version}")
230 set(HAVE_PYTHON_BS4 1 CACHE INTERNAL "")
234 if(PYTHON_DEFAULT_EXECUTABLE AND HAVE_PYTHON_BS4
235 AND OPENCV_PYTHON_SIGNATURES_FILE AND TARGET gen_opencv_python_source)
236 add_custom_target(doxygen_python
237 COMMAND ${PYTHON_DEFAULT_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/tools/add_signatures.py" "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/" "${OPENCV_PYTHON_SIGNATURES_FILE}" "python"
238 DEPENDS doxygen_cpp gen_opencv_python_source
239 COMMENT "Inject Python signatures into documentation"
241 add_custom_target(doxygen
242 DEPENDS doxygen_cpp doxygen_python
245 add_custom_target(doxygen
250 # Alias to build/install docs only
251 add_custom_target(install_docs
253 COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=docs -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
256 add_dependencies(opencv_docs doxygen)