tutorial4.docu 3.51 KB
Newer Older
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
/*! \page ex4 Create documentation for a plugin
 *
 * In this tutorial we will learn how to create automatically built
 * documentation for a custom plugin. We use \c doxygen for this purpose and
 * assume that you already made yourself familiar to it.
 *
 * \section ex4_openFlipperDoc The OpenFlipper documentation
 *
 * OpenFlipper provides its documentation and API references in two different
 * forms:
 *
 * - As html files generated by doxygen (once generated by calling \c doxygen they
 * can be found under the OpenFlipper/Docs directory in OpenFlipper's root folder).
 * These are basically the same files as one can find on the website.
 * - As compressed qt help file collection integrated into the application. They can be accessed
 * by chosing \c Help in OpenFlipper's menu bar.
 *
 * Now developers have the possibility to deliver their own plugin specific documentation
 * and integrate it into OpenFlipper's help system. Generating compressed qt help
 * files is supported by doxygen since version 1.5.7, therefore we recommend to use
 * the latest doxygen version in order to build compressed help files out of the documentation
 * that can be integrated into the application's help browser.
 *
 * \section ex4_start So let's start...
 *
 * In this tutorial we want to create the documentation of our plugin that we have
 * already created in \ref ex1. For this we go into our plugin's directory (here \c Plugin-SimplePlugin)
 * and create a directory named \c Doxygen. This is the directory that will contain all
 * the necessary docu-files. In this case we only create the file \c mainpage.docu.
 *
 * Now copy the file <code><b>Doxyfile.dox</b></code> (which can be found in <code><b>OpenFlipper/Doxygen/example</b></code>)
 * into your plugin's directory and name it <code><b>Doxyfile</b></code>.
 * Adapt the following project specific settings in the Doxyfile:
 *
 * \dontinclude Doxyfile.dox
 * \skipline PROJECT_NAME
 *
 * \dontinclude Doxyfile.dox
 * \skipline PROJECT_NUMBER
 *
 * \dontinclude Doxyfile.dox
 * \skipline QHP_VIRTUAL_FOLDER
 *
 * \dontinclude Doxyfile.dox
 * \skipline QCH_FILE
 *
 * \dontinclude Doxyfile.dox
 * \skipline QHP_NAMESPACE
 *
 * The last thing to be done is adding <code><b>Doc()</b></code> to your qmake project file.
 * This adds the target <code><b>doc</b></code> to the build system which builds the
 * plugin's documentation.
 *
 * \dontinclude Plugin-DocTest.pro
 * \skipline include
 * \until DIRECTORIES
 *
 * After executing qmake (make sure to use qmake version >= 4, some linux distributions
 * offer the symlink <code><b>qmake-qt4</b></code>) you just have to enter
 *
 * <br/><code><b>make doc</b></code><br/>
 *
 * to generate the documentation.
 *
 * All the files will be created in the folder Doc/html
 * in your plugin's directory. You can now open the index.html to see it.
 * When using doxygen >= 1.5.7 an additional .qch file (the filename can be specified
 * in the <b>Doxyfile</b>) has been generated and copied to <b>OpenFlipper/Help/</b>
 * in OpenFlipper's root directory. To integrate it into OpenFlipper's help browser
 * go to <b>OpenFlipper/Help/</b> and open <b>Help.qhcp</b> in a text editor.
 * Now add the line
 *
 * <br/><code><b>&lt;file&gt;plugin-doctest.qch&lt;/file&gt;</b></code><br/>
 *
 * under the <b>register</b> tag. The file now should look like this:
 *
 * \include Help.qhcp
 *
 * Now (still in <b>OpenFlipper/Help/</b>) execute
 *
 * <br/><code><b>qcollectiongenerator Help.qhcp -o Help.qhc</b></code><br/>
 *
 * Your documentation should now be available in OpenFlipper's help browser.
 */