Configuring Doxygen to generate a tag file.

shoeffner · shoeffner · commit 440e8d4efa6a · 2017-10-04T15:52:12.000+02:00
Additionally adds a tutorial on how to use the tag file in other projects to link back to the OpenCV documentation. The tutorial is also the only place which links to the tag file as of now. For more information on tag files and external documentation, check https://www.stack.nl/~dimitri/doxygen/manual/external.html
diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -255,7 +255,7 @@ PREDEFINED             = __cplusplus=1 \
 EXPAND_AS_DEFINED      =
 SKIP_FUNCTION_MACROS   = YES
 TAGFILES               =
-GENERATE_TAGFILE       =
+GENERATE_TAGFILE       = @CMAKE_DOXYGEN_OUTPUT_PATH@/html/opencv.tag
 ALLEXTERNALS           = NO
 EXTERNAL_GROUPS        = YES
 EXTERNAL_PAGES         = YES
diff --git a/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown b/doc/tutorials/introduction/cross_referencing/tutorial_cross_referencing.markdown
@@ -0,0 +1,61 @@
+Cross referencing OpenCV from other Doxygen projects {#tutorial_cross_referencing}
+====================================================
+
+Cross referencing OpenCV
+------------------------
+
+[Doxygen](https://www.stack.nl/~dimitri/doxygen/) is a tool to generate
+documentations like the OpenCV documentation you are reading right now.
+It is used by a variety of software projects and if you happen to use it
+to generate your own documentation, and you are using OpenCV inside your
+project, this short tutorial is for you.
+
+Imagine this warning inside your documentation code:
+
+@code
+/**
+ * @warning This functions returns a cv::Mat.
+ */
+@endcode
+
+Inside your generated documentation this warning will look roughly like this:
+
+@warning This functions returns a %cv::Mat.
+
+While inside the OpenCV documentation the `%cv::Mat` is rendered as a link:
+
+@warning This functions returns a cv::Mat.
+
+To generate links to the OpenCV documentation inside your project, you only
+have to perform two small steps. First download the file
+[opencv.tag](opencv.tag) (right-click and choose "save as...") and place it
+somewhere in your project directory, for example as
+`docs/doxygen-tags/opencv.tag`.
+
+Open your Doxyfile using your favorite text editor and search for the key
+`TAGFILES`. Change it as follows:
+
+@code
+TAGFILES = ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+If you had other definitions already, you can append the line using a `\`:
+
+@code
+TAGFILES = ./docs/doxygen-tags/libstdc++.tag=https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen \
+           ./docs/doxygen-tags/opencv.tag=http://docs.opencv.org/3.3.0
+@endcode
+
+Doxygen can now use the information from the tag file to link to the OpenCV
+documentation. Rebuild your documentation right now!
+
+@note To allow others to also use a *.tag file to link to your documentation,
+set `GENERATE_TAGFILE = html/your_project.tag`. Your documentation will now
+contain a `your_project.tag` file in its root directory.
+
+
+References
+----------
+
+- [Doxygen: Linking to external documentation](https://www.stack.nl/~dimitri/doxygen/manual/external.html)
+- [opencv.tag](opencv.tag)
diff --git a/doc/tutorials/introduction/table_of_content_introduction.markdown b/doc/tutorials/introduction/table_of_content_introduction.markdown
@@ -171,3 +171,11 @@ Additionally you can find very basic sample source code to introduce you to the
     _Author:_ Maksim Shabunin
 
     This document describes some aspects of 2.4 -> 3.0 transition process.
+
+-   @subpage tutorial_cross_referencing
+
+    _Compatibility:_ \> OpenCV 3.3.0
+
+    _Author:_ Sebastian Höffner
+
+    This document outlines how to create cross references to the OpenCV documentation from other Doxygen projects.
