doc/CMakeLists.txt

   1 if(NOT BUILD_DOCS)
   2   return()
   3 endif()
   4
   5 # Dependencies scheme (* - optional):
   6 #
   7 # javadoc* -> doxygen_javadoc* -> doxygen_cpp ---------> doxygen -> opencv_docs
   8 #    \                               \                     /        /
   9 #     \                               -> doxygen_python* ->        /
  10 #      ---------------------------------------------------------->
  11
  12 find_package(Doxygen)
  13 if(DOXYGEN_FOUND)
  14   add_custom_target(doxygen)
  15
  16   # not documented modules list
  17   list(APPEND blacklist "ts" "java_bindings_generator" "java" "python_bindings_generator" "python2" "python3" "js" "world")
  18   unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  19   unset(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT)
  20
  21   set(OPENCV_MATHJAX_RELPATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0" CACHE STRING "URI to a MathJax installation")
  22
  23   # gathering headers
  24   set(paths_include)
  25   set(paths_doc)
  26   set(paths_bib)
  27   set(paths_sample)
  28   set(paths_tutorial)
  29   set(paths_hal_interface)
  30   set(refs_main)
  31   set(refs_extra)
  32   set(deps)
  33   foreach(m ${OPENCV_MODULES_MAIN} ${OPENCV_MODULES_EXTRA})
  34     list(FIND blacklist ${m} _pos)
  35     if(${_pos} EQUAL -1)
  36       # include folder
  37       set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
  38       if(EXISTS "${header_dir}")
  39         list(APPEND paths_include "${header_dir}")
  40         list(APPEND deps ${header_dir})
  41       endif()
  42       # doc folder
  43       set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
  44       if(EXISTS "${docs_dir}")
  45         list(APPEND paths_doc "${docs_dir}")
  46         list(APPEND deps ${docs_dir})
  47       endif()
  48       # sample folder
  49       set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
  50       if(EXISTS "${sample_dir}")
  51         list(APPEND paths_sample "${sample_dir}")
  52         list(APPEND deps ${sample_dir})
  53       endif()
  54       # tutorial folder
  55       set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
  56       if(EXISTS "${tutorial_dir}")
  57         list(APPEND paths_tutorial "${tutorial_dir}")
  58         list(APPEND deps ${tutorial_dir})
  59
  60         # tutorial reference entry
  61         file(GLOB tutorials RELATIVE "${OPENCV_MODULE_opencv_${m}_LOCATION}" "${tutorial_dir}/*.markdown")
  62         foreach (t ${tutorials})
  63           if (NOT DEFINED CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  64             set(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT "- @ref tutorial_contrib_root")
  65             set(tutorial_contrib_root "${CMAKE_CURRENT_BINARY_DIR}/contrib_tutorials.markdown")
  66             file(WRITE "${tutorial_contrib_root}"
  67               "Tutorials for contrib modules {#tutorial_contrib_root}\n"
  68               "=============================\n")
  69           endif()
  70           file(STRINGS "${OPENCV_MODULE_opencv_${m}_LOCATION}/${t}" tutorial_id LIMIT_COUNT 1 REGEX ".*{#[^}]+}")
  71           string(REGEX REPLACE ".*{#([^}]+)}" "\\1" tutorial_id "${tutorial_id}")
  72           file(APPEND "${tutorial_contrib_root}" "- ${m}. @subpage ${tutorial_id}\n")
  73         endforeach()
  74       endif()
  75       # HAL replacement file
  76       set(replacement_header "${OPENCV_MODULE_opencv_${m}_LOCATION}/src/hal_replacement.hpp")
  77       if(EXISTS "${replacement_header}")
  78         list(APPEND paths_hal_interface "${replacement_header}")
  79       endif()
  80
  81       # BiBTeX file
  82       set(bib_file "${docs_dir}/${m}.bib")
  83       if(EXISTS "${bib_file}")
  84         set(paths_bib "${paths_bib} ${bib_file}")
  85         list(APPEND deps ${bib_file})
  86       endif()
  87       # Reference entry
  88       set(one_ref "\t- ${m}. @ref ${m}\n")
  89       list(FIND OPENCV_MODULES_EXTRA ${m} _pos)
  90       if(${_pos} EQUAL -1)
  91         set(refs_main "${refs_main}${one_ref}")
  92       else()
  93         set(refs_extra "${refs_extra}${one_ref}")
  94       endif()
  95     endif()
  96   endforeach()
  97
  98   # fix references
  99   # set(ref_header "Module name | Folder\n----------- | ------")
 100   # if(refs_main)
 101   #    set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
 102   # endif()
 103   # if(refs_extra)
 104   #   set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
 105   # endif()
 106   if(refs_main)
 107     set(refs_main "- Main modules:\n${refs_main}")
 108   endif()
 109   if(refs_extra)
 110     set(refs_extra "- Extra modules:\n${refs_extra}")
 111   endif()
 112
 113   # additional config
 114   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
 115   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
 116   set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
 117   set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
 118   set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
 119   set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
 120   set(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT "- @ref tutorial_js_root")
 121   set(tutorial_js_path "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials")
 122   set(example_path "${CMAKE_SOURCE_DIR}/samples")
 123
 124   # set export variables
 125   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}")
 126   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial}")
 127   # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
 128   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${example_path} ; ${paths_doc} ; ${paths_sample}")
 129   set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_BINARY_DIR}/DoxygenLayout.xml")
 130   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
 131   set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
 132   set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
 133   set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
 134   if (CMAKE_DOXYGEN_GENERATE_QHP)
 135     set(CMAKE_DOXYGEN_GENERATE_QHP "YES")
 136   else()
 137     set(CMAKE_DOXYGEN_GENERATE_QHP "NO")
 138   endif()
 139
 140   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/opencv.ico")
 141   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
 142   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
 143   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
 144   # list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
 145   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/tutorial-utils.js")
 146   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
 147
 148   # writing file
 149   configure_file(DoxygenLayout.xml DoxygenLayout.xml @ONLY)
 150   configure_file(Doxyfile.in ${doxyfile} @ONLY)
 151   configure_file(root.markdown.in ${rootfile} @ONLY)
 152
 153   # js tutorial assets
 154   set(opencv_tutorial_html_dir "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html")
 155   set(js_tutorials_assets_dir "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials/js_assets")
 156   set(js_tutorials_assets_deps "")
 157
 158   # make sure the build directory exists
 159   file(MAKE_DIRECTORY "${opencv_tutorial_html_dir}")
 160
 161   # gather and copy specific files for js tutorials
 162   file(GLOB_RECURSE js_assets "${js_tutorials_assets_dir}/*")
 163   ocv_list_filterout(js_assets "\\\\.eslintrc.json")
 164   list(APPEND js_assets "${OpenCV_SOURCE_DIR}/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.mp4")
 165
 166   if(BUILD_opencv_js)
 167     set(ocv_js_dir "${CMAKE_BINARY_DIR}/bin")
 168     set(ocv_js "opencv.js")
 169     list(APPEND js_assets "${ocv_js_dir}/${ocv_js}")
 170   elseif(DEFINED OPENCV_JS_LOCATION)
 171     list(APPEND js_assets "${OPENCV_JS_LOCATION}")
 172   endif()
 173
 174   # copy haar cascade files
 175   set(haar_cascade_files "")
 176   set(data_harrcascades_path "${OpenCV_SOURCE_DIR}/data/haarcascades/")
 177   list(APPEND js_tutorials_assets_deps "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 178   list(APPEND js_assets "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 179
 180   foreach(f ${js_assets})
 181     get_filename_component(fname "${f}" NAME)
 182     add_custom_command(OUTPUT "${opencv_tutorial_html_dir}/${fname}"
 183                        COMMAND ${CMAKE_COMMAND} -E copy_if_different "${f}" "${opencv_tutorial_html_dir}/${fname}"
 184                        DEPENDS "${f}"
 185                        COMMENT "Copying ${fname}"
 186     )
 187     list(APPEND js_tutorials_assets_deps "${f}" "${opencv_tutorial_html_dir}/${fname}")
 188   endforeach()
 189
 190   add_custom_target(
 191     doxygen_cpp
 192     COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
 193     DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps} ${js_tutorials_assets_deps}
 194     COMMENT "Generate Doxygen documentation"
 195   )
 196
 197   if(NOT DEFINED HAVE_PYTHON_BS4 AND PYTHON_DEFAULT_EXECUTABLE)
 198     # Documentation post-processing tool requires BuautifulSoup Python package
 199     execute_process(COMMAND "${PYTHON_DEFAULT_EXECUTABLE}" -c "import bs4; from bs4 import BeautifulSoup; print(bs4.__version__)"
 200                     RESULT_VARIABLE _result
 201                     OUTPUT_VARIABLE _bs4_version
 202                     OUTPUT_STRIP_TRAILING_WHITESPACE)
 203
 204     if(NOT _result EQUAL 0)
 205       set(HAVE_PYTHON_BS4 0 CACHE INTERNAL "")
 206     else()
 207       message(STATUS "Python BeautifulSoup (bs4) version: ${_bs4_version}")
 208       set(HAVE_PYTHON_BS4 1 CACHE INTERNAL "")
 209     endif()
 210   endif()
 211
 212   if(PYTHON_DEFAULT_EXECUTABLE
 213       AND HAVE_PYTHON_BS4
 214       AND OPENCV_PYTHON_SIGNATURES_FILE
 215       AND TARGET gen_opencv_python_source)
 216     add_custom_target(doxygen_python
 217       COMMAND ${PYTHON_DEFAULT_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/tools/add_signatures.py" "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/" "${OPENCV_PYTHON_SIGNATURES_FILE}" "python"
 218       DEPENDS doxygen_cpp gen_opencv_python_source
 219       COMMENT "Inject Python signatures into documentation"
 220     )
 221   endif()
 222
 223   add_dependencies(doxygen doxygen_cpp)
 224
 225   if(TARGET doxygen_python)
 226     add_dependencies(doxygen doxygen_python)
 227   endif()
 228
 229   if(TARGET doxygen_javadoc)
 230     add_dependencies(doxygen_cpp doxygen_javadoc)
 231   endif()
 232
 233   add_dependencies(opencv_docs doxygen)
 234
 235   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
 236     DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
 237     COMPONENT "docs" OPTIONAL
 238     ${compatible_MESSAGE_NEVER}
 239   )
 240 endif()