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 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" "world" "contrib_world")
  37   unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  38
  39   # gathering headers
  40   set(paths_include)
  41   set(paths_doc)
  42   set(paths_bib)
  43   set(paths_sample)
  44   set(paths_tutorial)
  45   set(refs_main)
  46   set(refs_extra)
  47   set(deps)
  48   foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
  49     list(FIND blacklist ${m} _pos)
  50     if(${_pos} EQUAL -1)
  51       # include folder
  52       set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
  53       if(EXISTS "${header_dir}")
  54         list(APPEND paths_include "${header_dir}")
  55         list(APPEND deps ${header_dir})
  56       endif()
  57       # doc folder
  58       set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
  59       if(EXISTS "${docs_dir}")
  60         list(APPEND paths_doc "${docs_dir}")
  61         list(APPEND deps ${docs_dir})
  62       endif()
  63       # sample folder
  64       set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
  65       if(EXISTS "${sample_dir}")
  66         list(APPEND paths_sample "${sample_dir}")
  67         list(APPEND deps ${sample_dir})
  68       endif()
  69       # tutorial folder
  70       set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
  71       if(EXISTS "${tutorial_dir}")
  72         list(APPEND paths_tutorial "${tutorial_dir}")
  73         list(APPEND deps ${tutorial_dir})
  74
  75         # tutorial reference entry
  76         file(GLOB tutorials RELATIVE "${OPENCV_MODULE_opencv_${m}_LOCATION}" "${tutorial_dir}/*.markdown")
  77         foreach (t ${tutorials})
  78           if (NOT DEFINED CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
  79             set(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT "- @ref tutorial_contrib_root")
  80             set(tutorial_contrib_root "${CMAKE_CURRENT_BINARY_DIR}/contrib_tutorials.markdown")
  81             file(WRITE "${tutorial_contrib_root}"
  82               "Tutorials for contrib modules {#tutorial_contrib_root}\n"
  83               "=============================\n")
  84           endif()
  85           file(STRINGS "${OPENCV_MODULE_opencv_${m}_LOCATION}/${t}" tutorial_id LIMIT_COUNT 1 REGEX ".*{#[^}]+}")
  86           string(REGEX REPLACE ".*{#([^}]+)}" "\\1" tutorial_id "${tutorial_id}")
  87           file(APPEND "${tutorial_contrib_root}" "- ${m}. @subpage ${tutorial_id}\n")
  88         endforeach()
  89       endif()
  90
  91       # BiBTeX file
  92       set(bib_file "${docs_dir}/${m}.bib")
  93       if(EXISTS "${bib_file}")
  94         set(paths_bib "${paths_bib} ${bib_file}")
  95         list(APPEND deps ${bib_file})
  96       endif()
  97       # Reference entry
  98     #   set(one_ref "@ref ${m} | ${m}\n")
  99       set(one_ref "\t- ${m}. @ref ${m}\n")
 100       list(FIND EXTRA_MODULES ${m} _pos)
 101       if(${_pos} EQUAL -1)
 102         set(refs_main "${refs_main}${one_ref}")
 103       else()
 104         set(refs_extra "${refs_extra}${one_ref}")
 105       endif()
 106     endif()
 107   endforeach()
 108
 109   # fix references
 110   # set(ref_header "Module name | Folder\n----------- | ------")
 111   # if(refs_main)
 112   #    set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
 113   # endif()
 114   # if(refs_extra)
 115   #   set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
 116   # endif()
 117   if(refs_main)
 118     set(refs_main "- Main modules:\n${refs_main}")
 119   endif()
 120   if(refs_extra)
 121     set(refs_extra "- Extra modules:\n${refs_extra}")
 122   endif()
 123
 124   # additional config
 125   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
 126   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
 127   set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
 128   set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
 129   set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
 130   set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
 131   set(example_path "${CMAKE_SOURCE_DIR}/samples")
 132
 133   # set export variables
 134   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${faqfile} ; ${paths_include} ; ${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${paths_tutorial} ; ${tutorial_contrib_root}")
 135   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${paths_tutorial}")
 136   # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
 137   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${example_path} ; ${paths_doc} ; ${paths_sample}")
 138   set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
 139   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
 140   set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
 141   set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
 142   set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
 143   if (CMAKE_DOXYGEN_GENERATE_QHP)
 144     set(CMAKE_DOXYGEN_GENERATE_QHP "YES")
 145   else()
 146     set(CMAKE_DOXYGEN_GENERATE_QHP "NO")
 147   endif()
 148
 149   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/opencv.ico")
 150   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
 151   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
 152   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
 153   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
 154   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
 155
 156   if(PLANTUML_JAR)
 157     set(CMAKE_DOXYGEN_PLANTUML_SUPPORT "PLANTUML_JAR_PATH      = ${PLANTUML_JAR}\n")
 158   else()
 159     set(CMAKE_DOXYGEN_PLANTUML_SUPPORT "ALIASES               += startuml{1}=\"@warning __No plantuml!__ \\n \\n @if DUMMY_PLANTUML_CODE\" enduml=\"@endif\"\n")
 160   endif()
 161
 162   # writing file
 163   configure_file(Doxyfile.in ${doxyfile} @ONLY)
 164   configure_file(root.markdown.in ${rootfile} @ONLY)
 165
 166   add_custom_target(doxygen
 167     COMMAND ${DOXYGEN_EXECUTABLE} ${doxyfile}
 168     DEPENDS ${doxyfile} ${rootfile} ${bibfile} ${deps}
 169   )
 170   install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
 171     DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
 172     COMPONENT "docs" OPTIONAL
 173   )
 174 endif()