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" "contrib_world")
  37   unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  38   unset(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT)
  39
  40   # gathering headers
  41   set(paths_include)
  42   set(paths_doc)
  43   set(paths_bib)
  44   set(paths_sample)
  45   set(paths_tutorial)
  46   set(paths_hal_interface)
  47   set(refs_main)
  48   set(refs_extra)
  49   set(deps)
  50   foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
  51     list(FIND blacklist ${m} _pos)
  52     if(${_pos} EQUAL -1)
  53       # include folder
  54       set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
  55       if(EXISTS "${header_dir}")
  56         list(APPEND paths_include "${header_dir}")
  57         list(APPEND deps ${header_dir})
  58       endif()
  59       # doc folder
  60       set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
  61       if(EXISTS "${docs_dir}")
  62         list(APPEND paths_doc "${docs_dir}")
  63         list(APPEND deps ${docs_dir})
  64       endif()
  65       # sample folder
  66       set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
  67       if(EXISTS "${sample_dir}")
  68         list(APPEND paths_sample "${sample_dir}")
  69         list(APPEND deps ${sample_dir})
  70       endif()
  71       # tutorial folder
  72       set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
  73       if(EXISTS "${tutorial_dir}")
  74         list(APPEND paths_tutorial "${tutorial_dir}")
  75         list(APPEND deps ${tutorial_dir})
  76
  77         # tutorial reference entry
  78         file(GLOB tutorials RELATIVE "${OPENCV_MODULE_opencv_${m}_LOCATION}" "${tutorial_dir}/*.markdown")
  79         foreach (t ${tutorials})
  80           if (NOT DEFINED CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  81             set(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT "- @ref tutorial_contrib_root")
  82             set(tutorial_contrib_root "${CMAKE_CURRENT_BINARY_DIR}/contrib_tutorials.markdown")
  83             file(WRITE "${tutorial_contrib_root}"
  84               "Tutorials for contrib modules {#tutorial_contrib_root}\n"
  85               "=============================\n")
  86           endif()
  87           file(STRINGS "${OPENCV_MODULE_opencv_${m}_LOCATION}/${t}" tutorial_id LIMIT_COUNT 1 REGEX ".*{#[^}]+}")
  88           string(REGEX REPLACE ".*{#([^}]+)}" "\\1" tutorial_id "${tutorial_id}")
  89           file(APPEND "${tutorial_contrib_root}" "- ${m}. @subpage ${tutorial_id}\n")
  90         endforeach()
  91       endif()
  92       # HAL replacement file
  93       set(replacement_header "${OPENCV_MODULE_opencv_${m}_LOCATION}/src/hal_replacement.hpp")
  94       if(EXISTS "${replacement_header}")
  95         list(APPEND paths_hal_interface "${replacement_header}")
  96       endif()
  97
  98       # BiBTeX file
  99       set(bib_file "${docs_dir}/${m}.bib")
 100       if(EXISTS "${bib_file}")
 101         set(paths_bib "${paths_bib} ${bib_file}")
 102         list(APPEND deps ${bib_file})
 103       endif()
 104       # Reference entry
 105     #   set(one_ref "@ref ${m} | ${m}\n")
 106       set(one_ref "\t- ${m}. @ref ${m}\n")
 107       list(FIND EXTRA_MODULES ${m} _pos)
 108       if(${_pos} EQUAL -1)
 109         set(refs_main "${refs_main}${one_ref}")
 110       else()
 111         set(refs_extra "${refs_extra}${one_ref}")
 112       endif()
 113     endif()
 114   endforeach()
 115
 116   # fix references
 117   # set(ref_header "Module name | Folder\n----------- | ------")
 118   # if(refs_main)
 119   #    set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
 120   # endif()
 121   # if(refs_extra)
 122   #   set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
 123   # endif()
 124   if(refs_main)
 125     set(refs_main "- Main modules:\n${refs_main}")
 126   endif()
 127   if(refs_extra)
 128     set(refs_extra "- Extra modules:\n${refs_extra}")
 129   endif()
 130
 131   # additional config
 132   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
 133   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
 134   set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
 135   set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
 136   set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
 137   set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
 138   set(CMAKE_DOXYGEN_TUTORIAL_JS_ROOT "- @ref tutorial_js_root")
 139   set(tutorial_js_path "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials")
 140   set(example_path "${CMAKE_SOURCE_DIR}/samples")
 141
 142   # set export variables
 143   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}")
 144   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial}")
 145   # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
 146   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${example_path} ; ${paths_doc} ; ${paths_sample}")
 147   set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
 148   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
 149   set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
 150   set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
 151   set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
 152   if (CMAKE_DOXYGEN_GENERATE_QHP)
 153     set(CMAKE_DOXYGEN_GENERATE_QHP "YES")
 154   else()
 155     set(CMAKE_DOXYGEN_GENERATE_QHP "NO")
 156   endif()
 157
 158   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/opencv.ico")
 159   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
 160   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
 161   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
 162   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
 163   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
 164
 165   # writing file
 166   configure_file(Doxyfile.in ${doxyfile} @ONLY)
 167   configure_file(root.markdown.in ${rootfile} @ONLY)
 168
 169   # js tutorial assets
 170   set(opencv_tutorial_html_dir "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html")
 171   set(js_tutorials_assets_dir "${CMAKE_CURRENT_SOURCE_DIR}/js_tutorials/js_assets")
 172   set(js_tutorials_assets_deps "")
 173
 174   # make sure the build directory exists
 175   file(MAKE_DIRECTORY "${opencv_tutorial_html_dir}")
 176
 177   # gather and copy specific files for js tutorials
 178   file(GLOB_RECURSE js_assets "${js_tutorials_assets_dir}/*")
 179   ocv_list_filterout(js_assets "\\\\.eslintrc.json")
 180   list(APPEND js_assets "${OpenCV_SOURCE_DIR}/samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/Data/box.mp4")
 181
 182   if(BUILD_opencv_js)
 183     set(ocv_js_dir "${CMAKE_BINARY_DIR}/bin")
 184     set(ocv_js "opencv.js")
 185     list(APPEND js_assets "${ocv_js_dir}/${ocv_js}")
 186   elseif(DEFINED OPENCV_JS_LOCATION)
 187     list(APPEND js_assets "${OPENCV_JS_LOCATION}")
 188   endif()
 189
 190   # copy haar cascade files
 191   set(haar_cascade_files "")
 192   set(data_harrcascades_path "${OpenCV_SOURCE_DIR}/data/haarcascades/")
 193   list(APPEND js_tutorials_assets_deps "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 194   list(APPEND js_assets "${data_harrcascades_path}/haarcascade_frontalface_default.xml" "${data_harrcascades_path}/haarcascade_eye.xml")
 195
 196   foreach(f ${js_assets})
 197     get_filename_component(fname "${f}" NAME)
 198     add_custom_command(OUTPUT "${opencv_tutorial_html_dir}/${fname}"
 199                        COMMAND ${CMAKE_COMMAND} -E copy_if_different "${f}" "${opencv_tutorial_html_dir}/${fname}"
 200                        DEPENDS "${f}"
 201                        COMMENT "Copying ${fname}"
 202     )
 203     list(APPEND js_tutorials_assets_deps "${f}" "${opencv_tutorial_html_dir}/${fname}")
 204   endforeach()
 205
 206   add_custom_target(doxygen
 207     COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
 208     DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps} ${js_tutorials_assets_deps}
 209   )
 210   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
 211     DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
 212     COMPONENT "docs" OPTIONAL
 213   )
 214
 215   # Alias to build/install docs only
 216   add_custom_target(install_docs
 217       DEPENDS doxygen
 218       COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=docs -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
 219   )
 220 endif()