doc/CMakeLists.txt

   1 #-----------------------
   2 #  CMake file for OpenCV docs
   3 #-----------------------
   4
   5 if(BUILD_DOCS AND DOXYGEN_FOUND)
   6   set(HAVE_DOC_GENERATOR TRUE)
   7 else()
   8   set(HAVE_DOC_GENERATOR FALSE)
   9 endif()
  10
  11 if(HAVE_DOC_GENERATOR)
  12   project(opencv_docs)
  13   # build lists of modules to be documented
  14   set(BASE_MODULES "")
  15   set(EXTRA_MODULES "")
  16
  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})
  21     else()
  22       list(APPEND EXTRA_MODULES ${mod})
  23     endif()
  24   endforeach()
  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)
  31
  32 # ========= Doxygen docs =========
  33
  34 if(BUILD_DOCS AND DOXYGEN_FOUND)
  35   # not documented modules list
  36   list(APPEND blacklist "ts" "java" "python2" "python3" "js" "world")
  37   unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  38   unset(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT)
  39
  40   set(OPENCV_MATHJAX_RELPATH "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.0" CACHE STRING "URI to a MathJax installation")
  41
  42   # gathering headers
  43   set(paths_include)
  44   set(paths_doc)
  45   set(paths_bib)
  46   set(paths_sample)
  47   set(paths_tutorial)
  48   set(paths_hal_interface)
  49   set(refs_main)
  50   set(refs_extra)
  51   set(deps)
  52   foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
  53     list(FIND blacklist ${m} _pos)
  54     if(${_pos} EQUAL -1)
  55       # include folder
  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})
  60       endif()
  61       # doc folder
  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})
  66       endif()
  67       # sample folder
  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})
  72       endif()
  73       # tutorial folder
  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})
  78
  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")
  88           endif()
  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")
  92         endforeach()
  93       endif()
  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}")
  98       endif()
  99
 100       # BiBTeX file
 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})
 105       endif()
 106       # Reference entry
 107     #   set(one_ref "@ref ${m} | ${m}\n")
 108       set(one_ref "\t- ${m}. @ref ${m}\n")
 109       list(FIND EXTRA_MODULES ${m} _pos)
 110       if(${_pos} EQUAL -1)
 111         set(refs_main "${refs_main}${one_ref}")
 112       else()
 113         set(refs_extra "${refs_extra}${one_ref}")
 114       endif()
 115     endif()
 116   endforeach()
 117
 118   # fix references
 119   # set(ref_header "Module name | Folder\n----------- | ------")
 120   # if(refs_main)
 121   #    set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
 122   # endif()
 123   # if(refs_extra)
 124   #   set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
 125   # endif()
 126   if(refs_main)
 127     set(refs_main "- Main modules:\n${refs_main}")
 128   endif()
 129   if(refs_extra)
 130     set(refs_extra "- Extra modules:\n${refs_extra}")
 131   endif()
 132
 133   # additional config
 134   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
 135   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
 136   set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
 137   set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
 138   set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
 139   set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
 140   set(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT "- @ref tutorial_js_root")
 141   set(tutorial_js_path "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials")
 142   set(example_path "${CMAKE_SOURCE_DIR}/samples")
 143
 144   # set export variables
 145   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}")
 146   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial}")
 147   # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
 148   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${example_path} ; ${paths_doc} ; ${paths_sample}")
 149   set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
 150   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
 151   set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
 152   set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
 153   set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
 154   if (CMAKE_DOXYGEN_GENERATE_QHP)
 155     set(CMAKE_DOXYGEN_GENERATE_QHP "YES")
 156   else()
 157     set(CMAKE_DOXYGEN_GENERATE_QHP "NO")
 158   endif()
 159
 160   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/opencv.ico")
 161   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
 162   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
 163   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
 164   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
 165   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
 166
 167   # writing file
 168   configure_file(Doxyfile.in ${doxyfile} @ONLY)
 169   configure_file(root.markdown.in ${rootfile} @ONLY)
 170
 171   # js tutorial assets
 172   set(opencv_tutorial_html_dir "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html")
 173   set(js_tutorials_assets_dir "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials/js_assets")
 174   set(js_tutorials_assets_deps "")
 175
 176   # make sure the build directory exists
 177   file(MAKE_DIRECTORY "${opencv_tutorial_html_dir}")
 178
 179   # gather and copy specific files for js tutorials
 180   file(GLOB_RECURSE js_assets "${js_tutorials_assets_dir}/*")
 181   ocv_list_filterout(js_assets "\\\\.eslintrc.json")
 182   list(APPEND js_assets "${OpenCV_SOURCE_DIR}/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.mp4")
 183
 184   if(BUILD_opencv_js)
 185     set(ocv_js_dir "${CMAKE_BINARY_DIR}/bin")
 186     set(ocv_js "opencv.js")
 187     list(APPEND js_assets "${ocv_js_dir}/${ocv_js}")
 188   elseif(DEFINED OPENCV_JS_LOCATION)
 189     list(APPEND js_assets "${OPENCV_JS_LOCATION}")
 190   endif()
 191
 192   # copy haar cascade files
 193   set(haar_cascade_files "")
 194   set(data_harrcascades_path "${OpenCV_SOURCE_DIR}/data/haarcascades/")
 195   list(APPEND js_tutorials_assets_deps "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 196   list(APPEND js_assets "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 197
 198   foreach(f ${js_assets})
 199     get_filename_component(fname "${f}" NAME)
 200     add_custom_command(OUTPUT "${opencv_tutorial_html_dir}/${fname}"
 201                        COMMAND ${CMAKE_COMMAND} -E copy_if_different "${f}" "${opencv_tutorial_html_dir}/${fname}"
 202                        DEPENDS "${f}"
 203                        COMMENT "Copying ${fname}"
 204     )
 205     list(APPEND js_tutorials_assets_deps "${f}" "${opencv_tutorial_html_dir}/${fname}")
 206   endforeach()
 207
 208   add_custom_target(doxygen
 209     COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
 210     DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps} ${js_tutorials_assets_deps}
 211   )
 212   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
 213     DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
 214     COMPONENT "docs" OPTIONAL
 215   )
 216
 217   # Alias to build/install docs only
 218   add_custom_target(install_docs
 219       DEPENDS doxygen
 220       COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=docs -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
 221   )
 222 endif()