diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 1276a6b9c8..382255468f 100644 --- 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 new file mode 100644 index 0000000000..acc788d84e --- /dev/null +++ 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 index 37820a8e1b..ebd2793039 100644 --- 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.