From d3beb755dfca788390142e11a228da76802081c2 Mon Sep 17 00:00:00 2001 From: Maksim Shabunin Date: Mon, 1 Dec 2014 19:22:04 +0300 Subject: [PATCH] Doxygen tutorials: support contrib, some minor changes --- doc/CMakeLists.txt | 68 ++++++++++++++----- doc/faq.markdown | 11 +++ .../py_setup_in_windows.markdown | 2 +- doc/py_tutorials/py_tutorials.markdown | 2 +- doc/root.markdown.in | 15 ++-- .../real_time_pose/real_time_pose.markdown | 2 +- .../feature_description.markdown | 2 +- .../feature_detection.markdown | 2 +- .../background_subtraction.markdown | 2 +- 9 files changed, 73 insertions(+), 33 deletions(-) create mode 100644 doc/faq.markdown diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt index ebad5454c..cc54e7414 100644 --- a/doc/CMakeLists.txt +++ b/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}") - 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(example_path "${CMAKE_SOURCE_DIR}/samples") + + # 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" diff --git a/doc/faq.markdown b/doc/faq.markdown new file mode 100644 index 000000000..3bbaa8246 --- /dev/null +++ b/doc/faq.markdown @@ -0,0 +1,11 @@ +Frequently Asked Questions {#faq} +========================== + +- Q: Example question? + + A: Example answer + + +- Q: Example question? + + A: Example answer diff --git a/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown b/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown index 32fc7a6cd..807e5467b 100644 --- a/doc/py_tutorials/py_setup/py_setup_in_windows/py_setup_in_windows.markdown +++ b/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. diff --git a/doc/py_tutorials/py_tutorials.markdown b/doc/py_tutorials/py_tutorials.markdown index 1c3df854e..532da4e7e 100644 --- a/doc/py_tutorials/py_tutorials.markdown +++ b/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 diff --git a/doc/root.markdown.in b/doc/root.markdown.in index 72095780c..3a781a5ed 100644 --- a/doc/root.markdown.in +++ b/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@ diff --git a/doc/tutorials/calib3d/real_time_pose/real_time_pose.markdown b/doc/tutorials/calib3d/real_time_pose/real_time_pose.markdown index ee54e4d38..e88585b4d 100644 --- a/doc/tutorials/calib3d/real_time_pose/real_time_pose.markdown +++ b/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. diff --git a/doc/tutorials/features2d/feature_description/feature_description.markdown b/doc/tutorials/features2d/feature_description/feature_description.markdown index 9a71b131b..047fa5ba0 100644 --- a/doc/tutorials/features2d/feature_description/feature_description.markdown +++ b/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. diff --git a/doc/tutorials/features2d/feature_detection/feature_detection.markdown b/doc/tutorials/features2d/feature_detection/feature_detection.markdown index 09e7d6f30..8b2f423ee 100644 --- a/doc/tutorials/features2d/feature_detection/feature_detection.markdown +++ b/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 diff --git a/doc/tutorials/video/background_subtraction/background_subtraction.markdown b/doc/tutorials/video/background_subtraction/background_subtraction.markdown index bf4f3bd89..6e425c9f1 100644 --- a/doc/tutorials/video/background_subtraction/background_subtraction.markdown +++ b/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.