Merge pull request #10621 from mshabunin:disable-docs

Documentation generation refactoring (#10621)

* Documentation build updates:

- disable documentation by default, do not add to ALL target
- combine Doxygen and Javadoc
- optimize Doxygen html

* javadoc: fix path in build directory

* cmake: fix "Documentation" status line

doc/CMakeLists.txt

@@ -1,37 +1,18 @@
-#-----------------------
-#  CMake file for OpenCV docs
-#-----------------------
-
-if(BUILD_DOCS AND DOXYGEN_FOUND)
-  set(HAVE_DOC_GENERATOR TRUE)
-else()
-  set(HAVE_DOC_GENERATOR FALSE)
+if(NOT BUILD_DOCS)
+  return()
 endif()
 
-if(HAVE_DOC_GENERATOR)
-  project(opencv_docs)
-  # build lists of modules to be documented
-  set(BASE_MODULES "")
-  set(EXTRA_MODULES "")
+# Dependencies scheme (* - optional):
+#
+# javadoc* -> doxygen_javadoc* -> doxygen_cpp ---------> doxygen -> opencv_docs
+#    \                               \                     /        /
+#     \                               -> doxygen_python* ->        /
+#      ---------------------------------------------------------->
 
-  foreach(mod ${OPENCV_MODULES_BUILD} ${OPENCV_MODULES_DISABLED_USER} ${OPENCV_MODULES_DISABLED_AUTO} ${OPENCV_MODULES_DISABLED_FORCE})
-    string(REGEX REPLACE "^opencv_" "" mod "${mod}")
-    if("${OPENCV_MODULE_opencv_${mod}_LOCATION}" STREQUAL "${OpenCV_SOURCE_DIR}/modules/${mod}")
-      list(APPEND BASE_MODULES ${mod})
-    else()
-      list(APPEND EXTRA_MODULES ${mod})
-    endif()
-  endforeach()
-  ocv_list_sort(BASE_MODULES)
-  ocv_list_sort(EXTRA_MODULES)
-  set(FIXED_ORDER_MODULES core imgproc imgcodecs videoio highgui video calib3d features2d objdetect dnn ml flann photo stitching)
-  list(REMOVE_ITEM BASE_MODULES ${FIXED_ORDER_MODULES})
-  set(BASE_MODULES ${FIXED_ORDER_MODULES} ${BASE_MODULES})
-endif(HAVE_DOC_GENERATOR)
+find_package(Doxygen)
+if(DOXYGEN_FOUND)
+  add_custom_target(doxygen)
 
-# ========= Doxygen docs =========
-
-if(BUILD_DOCS AND DOXYGEN_FOUND)
   # not documented modules list
   list(APPEND blacklist "ts" "java_bindings_generator" "java" "python_bindings_generator" "python2" "python3" "js" "world")
   unset(CMAKE_DOXYGEN_TUTORIAL_CONTRIB_ROOT)
@@ -49,7 +30,7 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
   set(refs_main)
   set(refs_extra)
   set(deps)
-  foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
+  foreach(m ${OPENCV_MODULES_MAIN} ${OPENCV_MODULES_EXTRA})
     list(FIND blacklist ${m} _pos)
     if(${_pos} EQUAL -1)
       # include folder
@@ -105,7 +86,7 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
       endif()
       # Reference entry
       set(one_ref "\t- ${m}. @ref ${m}\n")
-      list(FIND EXTRA_MODULES ${m} _pos)
+      list(FIND OPENCV_MODULES_EXTRA ${m} _pos)
       if(${_pos} EQUAL -1)
         set(refs_main "${refs_main}${one_ref}")
       else()
@@ -145,7 +126,7 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${tutorial_js_path} ; ${paths_tutorial}")
   # TODO: remove paths_doc from EXAMPLE_PATH after face module tutorials/samples moved to separate folders
   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${example_path} ; ${paths_doc} ; ${paths_sample}")
-  set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
+  set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_BINARY_DIR}/DoxygenLayout.xml")
   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
   set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
   set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
@@ -160,10 +141,12 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png")
   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/acircles_pattern.png")
   list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/bodybg.png")
-  list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
+  # list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/mymath.sty")
+  list(APPEND CMAKE_DOXYGEN_HTML_FILES "${CMAKE_CURRENT_SOURCE_DIR}/tutorial-utils.js")
   string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_HTML_FILES "${CMAKE_DOXYGEN_HTML_FILES}")
 
   # writing file
+  configure_file(DoxygenLayout.xml DoxygenLayout.xml @ONLY)
   configure_file(Doxyfile.in ${doxyfile} @ONLY)
   configure_file(root.markdown.in ${rootfile} @ONLY)
 
@@ -211,11 +194,6 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
     COMMENT "Generate Doxygen documentation"
   )
 
-  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
-    DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
-    COMPONENT "docs" OPTIONAL
-  )
-
   if(NOT DEFINED HAVE_PYTHON_BS4 AND PYTHON_DEFAULT_EXECUTABLE)
     # Documentation post-processing tool requires BuautifulSoup Python package
     execute_process(COMMAND "${PYTHON_DEFAULT_EXECUTABLE}" -c "import bs4; from bs4 import BeautifulSoup; print(bs4.__version__)"
@@ -231,27 +209,32 @@ if(BUILD_DOCS AND DOXYGEN_FOUND)
     endif()
   endif()
 
-  if(PYTHON_DEFAULT_EXECUTABLE AND HAVE_PYTHON_BS4
-      AND OPENCV_PYTHON_SIGNATURES_FILE AND TARGET gen_opencv_python_source)
+  if(PYTHON_DEFAULT_EXECUTABLE
+      AND HAVE_PYTHON_BS4
+      AND OPENCV_PYTHON_SIGNATURES_FILE
+      AND TARGET gen_opencv_python_source)
     add_custom_target(doxygen_python
       COMMAND ${PYTHON_DEFAULT_EXECUTABLE} "${CMAKE_CURRENT_SOURCE_DIR}/tools/add_signatures.py" "${CMAKE_CURRENT_BINARY_DIR}/doxygen/html/" "${OPENCV_PYTHON_SIGNATURES_FILE}" "python"
       DEPENDS doxygen_cpp gen_opencv_python_source
       COMMENT "Inject Python signatures into documentation"
     )
-    add_custom_target(doxygen
-      DEPENDS doxygen_cpp doxygen_python
-    )
-  else()
-    add_custom_target(doxygen
-      DEPENDS doxygen_cpp
-    )
   endif()
 
-  # Alias to build/install docs only
-  add_custom_target(install_docs
-      DEPENDS doxygen
-      COMMAND "${CMAKE_COMMAND}" -DCMAKE_INSTALL_COMPONENT=docs -P "${CMAKE_BINARY_DIR}/cmake_install.cmake"
-  )
+  add_dependencies(doxygen doxygen_cpp)
+
+  if(TARGET doxygen_python)
+    add_dependencies(doxygen doxygen_python)
+  endif()
+
+  if(TARGET doxygen_javadoc)
+    add_dependencies(doxygen_cpp doxygen_javadoc)
+  endif()
 
   add_dependencies(opencv_docs doxygen)
+
+  install(DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/doxygen/html
+    DESTINATION "${OPENCV_DOC_INSTALL_PATH}"
+    COMPONENT "docs" OPTIONAL
+    ${compatible_MESSAGE_NEVER}
+  )
 endif()