Doxygen tutorials: support contrib, some minor changes

doc/CMakeLists.txt

@@ -147,17 +147,6 @@ endif()
 
 # ========= Doxygen docs =========
 
-macro(make_reference result modules_list black_list)
-    set(_res)
-    foreach(m ${${modules_list}})
-        list(FIND ${black_list} ${m} _pos)
-        if(${_pos} EQUAL -1)
-            set(_res "${_res} @ref ${m} | ${m} \n")
-        endif()
-    endforeach()
-    set(${result} ${_res})
-endmacro()
-
 if(BUILD_DOCS AND HAVE_DOXYGEN)
   # not documented modules list
   list(APPEND blacklist "ts" "java" "python2" "python3" "world")
@@ -166,6 +155,10 @@ if(BUILD_DOCS AND HAVE_DOXYGEN)
   set(paths_include)
   set(paths_doc)
   set(paths_bib)
+  set(paths_sample)
+  set(paths_tutorial)
+  set(refs_main)
+  set(refs_extra)
   set(deps)
   foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
     list(FIND blacklist ${m} _pos)
@@ -182,40 +175,79 @@ if(BUILD_DOCS AND HAVE_DOXYGEN)
         list(APPEND paths_doc "${docs_dir}")
         list(APPEND deps ${docs_dir})
       endif()
+      # sample folder
+      set(sample_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/samples")
+      if(EXISTS "${sample_dir}")
+        list(APPEND paths_sample "${sample_dir}")
+        list(APPEND deps ${sample_dir})
+      endif()
+      # tutorial folder
+      set(tutorial_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/tutorials")
+      if(EXISTS "${tutorial_dir}")
+        list(APPEND paths_tutorial "${tutorial_dir}")
+        list(APPEND deps ${tutorial_dir})
+      endif()
       # BiBTeX file
       set(bib_file "${docs_dir}/${m}.bib")
       if(EXISTS "${bib_file}")
         set(paths_bib "${paths_bib} ${bib_file}")
         list(APPEND deps ${bib_file})
       endif()
+      # Reference entry
+    #   set(one_ref "@ref ${m} | ${m}\n")
+      set(one_ref "\t- ${m}. @ref ${m}\n")
+      list(FIND EXTRA_MODULES ${m} _pos)
+      if(${_pos} EQUAL -1)
+        set(refs_main "${refs_main}${one_ref}")
+      else()
+        set(refs_extra "${refs_extra}${one_ref}")
+      endif()
     endif()
   endforeach()
 
+  # fix references
+  # set(ref_header "Module name | Folder\n----------- | ------")
+  # if(refs_main)
+  #    set(refs_main "### Main modules\n${ref_header}\n${refs_main}")
+  # endif()
+  # if(refs_extra)
+  #   set(refs_extra "### Extra modules\n${ref_header}\n${refs_extra}")
+  # endif()
+  if(refs_main)
+    set(refs_main "- Main modules:\n${refs_main}")
+  endif()
+  if(refs_extra)
+    set(refs_extra "- Extra modules:\n${refs_extra}")
+  endif()
 
   # additional config
   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
   set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
+  set(faqfile "${CMAKE_CURRENT_SOURCE_DIR}/faq.markdown")
   set(tutorial_path "${CMAKE_CURRENT_SOURCE_DIR}/tutorials")
   set(tutorial_py_path "${CMAKE_CURRENT_SOURCE_DIR}/py_tutorials")
   set(user_guide_path "${CMAKE_CURRENT_SOURCE_DIR}/user_guide")
-  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${paths_include} ; ${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${user_guide_path}")
+  set(example_path "${CMAKE_SOURCE_DIR}/samples")
-  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path}")
+
-  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${CMAKE_SOURCE_DIR}/samples ; ${paths_doc}")
+  # set export variables
+  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${faqfile} ; ${paths_include} ; ${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${user_guide_path} ; ${paths_tutorial}")
+  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc} ; ${tutorial_path} ; ${tutorial_py_path} ; ${user_guide_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_OUTPUT_PATH "doxygen")
+  set(CMAKE_DOXYGEN_MAIN_REFERENCE "${refs_main}")
+  set(CMAKE_DOXYGEN_EXTRA_REFERENCE "${refs_extra}")
   set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
 
-  # generate references
-  make_reference(CMAKE_DOXYGEN_MAIN_REFERENCE BASE_MODULES blacklist)
-  make_reference(CMAKE_DOXYGEN_EXTRA_REFERENCE EXTRA_MODULES blacklist)
-
   # writing file
   configure_file(Doxyfile.in ${doxyfile} @ONLY)
   configure_file(root.markdown.in ${rootfile} @ONLY)
   configure_file(mymath.sty "${CMAKE_DOXYGEN_OUTPUT_PATH}/html/mymath.sty" @ONLY)
   configure_file(mymath.sty "${CMAKE_DOXYGEN_OUTPUT_PATH}/latex/mymath.sty" @ONLY)
 
+  # TODO: do not store downloadable samples, but give github link instead
   add_custom_target(doxygen
     COMMAND "${CMAKE_COMMAND}" -E copy_directory "${CMAKE_SOURCE_DIR}/samples" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html/samples"
     COMMAND "${CMAKE_COMMAND}" -E copy "${CMAKE_CURRENT_SOURCE_DIR}/pattern.png" "${CMAKE_DOXYGEN_OUTPUT_PATH}/html"

doc/faq.markdown

@@ -0,0 +1,11 @@
+Frequently Asked Questions {#faq}
+==========================
+
+-   Q: Example question?
+
+    A: Example answer
+
+
+-   Q: Example question?
+
+    A: Example answer

doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown

@@ -21,7 +21,7 @@ Installing OpenCV from prebuilt binaries
 
     -#  [Matplotlib](https://downloads.sourceforge.net/project/matplotlib/matplotlib/matplotlib-1.3.0/matplotlib-1.3.0.win32-py2.7.exe) (*Matplotlib is optional, but recommended since we use it a lot in our tutorials*).
 
--#  Install all packages into their default locations. Python will be installed to **C:/Python27/**.
+-#  Install all packages into their default locations. Python will be installed to `C:/Python27/`.
 
 -#  After installation, open Python IDLE. Enter import numpy and make sure Numpy is working fine.
 

doc/py_tutorials/py_tutorials.markdown

@@ -1,4 +1,4 @@
-OpenCV-Python Tutorials {#tutorial_py_tutorials}
+OpenCV-Python Tutorials {#tutorial_py_root}
 =======================
 
 -   @subpage tutorial_py_table_of_contents_setup

doc/root.markdown.in

@@ -1,16 +1,13 @@
 OpenCV modules {#mainpage}
 ==============
 
-@subpage intro
+- @ref intro
+- @ref tutorial_root
+- @ref tutorial_py_root
+- @ref tutorial_user_guide
+- @ref faq
+- @ref citelist
 
-### Main modules
-
- Module name   | Folder
--------------- | -------------
 @CMAKE_DOXYGEN_MAIN_REFERENCE@
 
-### Extra modules
-
- Module name   | Folder
--------------- | -------------
 @CMAKE_DOXYGEN_EXTRA_REFERENCE@

doc/tutorials/calib3d/real_time_pose/real_time_pose.markdown

@@ -244,7 +244,7 @@ Here is explained in detail the code for the real time application:
     extraction. You can find it in
     `samples/cpp/tutorial_code/calib3d/real_time_pose_estimation/src/RobusMatcher.cpp`. In your
     *RobusMatch* object you can use any of the 2D features detectors of OpenCV. In this case I used
-    @ref cv::ORB features because is based on @ref cv::FAST to detect the keypoints and @ref cv::xfeatures2d::BriefDescriptorExtractor
+    @ref cv::ORB features because is based on @ref cv::FAST to detect the keypoints and cv::xfeatures2d::BriefDescriptorExtractor
     to extract the descriptors which means that is fast and robust to rotations. You can find more
     detailed information about *ORB* in the documentation.
 

doc/tutorials/features2d/feature_description/feature_description.markdown

@@ -8,7 +8,7 @@ In this tutorial you will learn how to:
 
 -   Use the @ref cv::DescriptorExtractor interface in order to find the feature vector correspondent
     to the keypoints. Specifically:
-    -   Use @ref cv::xfeatures2d::SURF and its function @ref cv::xfeatures2d::SURF::compute to perform the
+    -   Use cv::xfeatures2d::SURF and its function cv::xfeatures2d::SURF::compute to perform the
         required calculations.
     -   Use a @ref cv::BFMatcher to match the features vector
     -   Use the function @ref cv::drawMatches to draw the detected matches.

doc/tutorials/features2d/feature_detection/feature_detection.markdown

@@ -7,7 +7,7 @@ Goal
 In this tutorial you will learn how to:
 
 -   Use the @ref cv::FeatureDetector interface in order to find interest points. Specifically:
-    -   Use the @ref cv::xfeatures2d::SURF and its function @ref cv::xfeatures2d::SURF::detect to perform the
+    -   Use the cv::xfeatures2d::SURF and its function cv::xfeatures2d::SURF::detect to perform the
         detection process
     -   Use the function @ref cv::drawKeypoints to draw the detected keypoints
 

doc/tutorials/video/background_subtraction/background_subtraction.markdown

@@ -41,7 +41,7 @@ In the following you can find the source code. We will let the user chose to pro
 file or a sequence of images.
 
 Two different methods are used to generate two foreground masks:
--#  @ref cv::bgsegm::BackgroundSubtractorMOG
+-#  cv::bgsegm::BackgroundSubtractorMOG
 -#  @ref cv::BackgroundSubtractorMOG2
 
 The results as well as the input data are shown on the screen.