|
1 /****************************************************************************** |
|
2 * |
|
3 * |
|
4 * |
|
5 * Copyright (C) 1997-2008 by Dimitri van Heesch. |
|
6 * |
|
7 * Permission to use, copy, modify, and distribute this software and its |
|
8 * documentation under the terms of the GNU General Public License is hereby |
|
9 * granted. No representations are made about the suitability of this software |
|
10 * for any purpose. It is provided "as is" without express or implied warranty. |
|
11 * See the GNU General Public License for more details. |
|
12 * |
|
13 * Documents produced by Doxygen are derivative works derived from the |
|
14 * input used in their production; they are not affected by this license. |
|
15 * |
|
16 */ |
|
17 /*! \page customize Customizing the output |
|
18 |
|
19 Doxygen provides various levels of customization. |
|
20 The \ref minor_tweaks "first section" discusses what to |
|
21 do if you want to do minor tweaker to the look and feel of the output. |
|
22 The \ref layout "next" section show how to reorder and hide certain |
|
23 information on a page. |
|
24 The \ref xmlgenerator "last" section show how to generate whatever output |
|
25 you want based on the XML output produced by doxygen. |
|
26 |
|
27 \section minor_tweaks Minor Tweaks |
|
28 |
|
29 To simply tweak things like fonts or colors, margins, or other look \& feel |
|
30 espects of the HTML output you can create a different |
|
31 <a href="http://www.w3schools.com/css/default.asp">cascading style sheet</a>. |
|
32 You can also let doxygen use a custom header and footer for each HTML |
|
33 page it generates, for instance to include a logo or to make the |
|
34 doxygen output blend in with the rest of the web site. |
|
35 |
|
36 To do this first run doxygen as follows: |
|
37 \verbatim |
|
38 doxygen -w html header.html footer.html customdoxygen.css |
|
39 \endverbatim |
|
40 |
|
41 This will create 3 files: |
|
42 - header.html is a HTML fragment which doxygen normally uses to start |
|
43 a HTML page. Note that the fragment ends with a body tag and that is |
|
44 contains a couple of commands of the form \$word. These will be replaced |
|
45 by doxygen on the fly. |
|
46 - footer.html is a HTML fragment which doxygen normally uses to end |
|
47 a HTML page. Also here special commands can be used. This file contain the |
|
48 link to www.doxygen.org and the body and html end tags. |
|
49 - customdoxygen.css is the default cascading style sheet |
|
50 used by doxygen. |
|
51 |
|
52 You should edit these files and then reference them from the config file. |
|
53 \verbatim |
|
54 HTML_HEADER = header.html |
|
55 HTML_FOOTER = footer.html |
|
56 HTML_STYLESHEET = customdoxygen.css |
|
57 \endverbatim |
|
58 |
|
59 See the documentation of the \ref cfg_html_header "HTML_HEADER" tag |
|
60 for more information about the possible meta commands. |
|
61 |
|
62 \note You should not put the style sheet in the HTML output directory. Treat |
|
63 it is a source file. Doxygen will copy it for you. |
|
64 |
|
65 \note If you use images or other external content in a custom header you |
|
66 need to make sure these end up in the HTML output directory yourself, |
|
67 for instance by writing a script that runs doxygen can then copies the |
|
68 images to the output. |
|
69 |
|
70 |
|
71 \section layout Changing the layout of pages |
|
72 |
|
73 In some cases you may want to change the way the output is structured. |
|
74 A different style sheet or custom headers and footers do not help in such |
|
75 case. |
|
76 |
|
77 The solution doxygen provides is a layout file, which you can |
|
78 modify and doxygen will use to control what information is presented, |
|
79 in which order, and to some extent also how information is presented. |
|
80 The layout file is an XML file. |
|
81 |
|
82 The default layout can be generated |
|
83 by doxygen using the following command: |
|
84 \verbatim |
|
85 doxygen -l |
|
86 \endverbatim |
|
87 optionally the name of the layout file can be specified, if omitted |
|
88 \c DoxygenLayout.xml will be used. |
|
89 |
|
90 The next step is to mention the layout file in the config file |
|
91 \verbatim |
|
92 LAYOUT_FILE = DoxygenLayout.xml |
|
93 \endverbatim |
|
94 The change the layout all you need to do is edit the layout file. |
|
95 |
|
96 The toplevel structure of the file looks as follows: |
|
97 \verbatim |
|
98 <doxygenlayout version="1.0"> |
|
99 <navindex> |
|
100 ... |
|
101 </navindex> |
|
102 <class> |
|
103 ... |
|
104 </class> |
|
105 <namespace> |
|
106 ... |
|
107 </namespace> |
|
108 <file> |
|
109 ... |
|
110 </file> |
|
111 <group> |
|
112 ... |
|
113 </group> |
|
114 <directory> |
|
115 ... |
|
116 </directory> |
|
117 </doxygenlayout> |
|
118 \endverbatim |
|
119 |
|
120 The root tag of the XML is \c doxygenlayout, it has an attribute named |
|
121 \c version, which will be used in the future to cope with changes that are |
|
122 not backward compatible. |
|
123 |
|
124 The first section, enclosed by \c navindex tags represents the layout of |
|
125 the navigation tabs displayed at the top of each HTML page. |
|
126 Each tab is represented by a \c tab tag in the XML file. |
|
127 |
|
128 You can hide tabs by setting the \c visible attribute to \c no. |
|
129 You can also override the default title of a tab by specifying it as |
|
130 the value of the \c title attribute. If the title field is the empty string |
|
131 (the default) then doxygen will fill in an appropriate title. |
|
132 You can reorder the tabs by moving the tab tags in the XML file |
|
133 within the \c navindex section and even change the tree structure. |
|
134 Do not change the value of the \c type attribute however. |
|
135 Only a fixed set of types are supported, each representing a link to a |
|
136 specific index. |
|
137 |
|
138 The sections after \c navindex represent the layout of the different |
|
139 pages generated by doxygen: |
|
140 - The \c class section represents the layout of all pages generated for |
|
141 documented classes, structs, unions, and interfaces. |
|
142 - The \c namespace section represents the layout of all pages generated for |
|
143 documented namespaces (and also Java packages). |
|
144 - The \c file section represents the layout of all pages generated for |
|
145 documented files. |
|
146 - The \c group section represents the layout of all pages generated for |
|
147 documented groups (or modules). |
|
148 - The \c directory section represents the layout of all pages generated for |
|
149 documented directories. |
|
150 |
|
151 Each XML tag within one of the above page sections represents a certain |
|
152 piece of information. Some pieces can appear in each type of page, |
|
153 others are specific for a certain type of page. |
|
154 Doxygen will list the pieces in the order in which they appear |
|
155 in the XML file. |
|
156 |
|
157 Some tags have a \c visible attribute which can be |
|
158 used to hide the fragment from the generated output, by setting the attribute's |
|
159 value to "no". You can also use the value of a configuration option to |
|
160 determine the visibility, by using |
|
161 its name prefixed with a dollar sign, e.g. |
|
162 \verbatim |
|
163 ... |
|
164 <includes visible="$SHOW_INCLUDE_FILES"/> |
|
165 ... |
|
166 \endverbatim |
|
167 This was mainly added for backward compatibility. |
|
168 Note that the \c visible attribute is just a hint for doxygen. |
|
169 If no relevant information is available for a certain piece it is |
|
170 omitted even if it is set to \c yes (i.e. no empty sections are generated). |
|
171 |
|
172 Some tags have a \c title attribute. This attribute can be used |
|
173 to customize the title doxygen will use as a header for the piece. |
|
174 |
|
175 @warning at the moment you should not remove tags from the layout file |
|
176 as a way to hide information. Doing so can cause broken links in the |
|
177 generated output! |
|
178 |
|
179 At the moment the following generic tags are possible for each page: |
|
180 <dl> |
|
181 <dt>\c briefdescription |
|
182 <dd>Represents the brief description on a page. |
|
183 <dt>\c detaileddescription |
|
184 <dd>Represents the detailed description on a page. |
|
185 <dt>\c authorsection |
|
186 <dd>Represents the author section of a page (only used for man pages). |
|
187 <dt>\c memberdecl |
|
188 <dd>Represents the quick overview of members on a page (member declarations). |
|
189 This tag has child tags each representing a list of |
|
190 members of a certain type. |
|
191 The possible child tags are not listed in detail in the document, |
|
192 but the name of the tag should be a good indication of the type |
|
193 of members that the tag represents. |
|
194 <dt>\c memberdef |
|
195 <dd>Represents the detailed member list on a page (member definition). |
|
196 Like the \c memberdecl tag, also this tag has a number of |
|
197 possible child tags. |
|
198 </dl> |
|
199 |
|
200 The class page has the following specific tags: |
|
201 <dl> |
|
202 <dt>\c includes |
|
203 <dd>Represents the include file needed to obtain the definition for |
|
204 this class. |
|
205 <dt>\c inheritancegraph |
|
206 <dd>Represents the inheritance relations for a class. |
|
207 Note that the CLASS_DIAGRAM option determines |
|
208 if the inheritance relation is a list of base and derived classes or |
|
209 a graph. |
|
210 <dt>\c collaborationgraph |
|
211 <dd>Represents the collaboration graph for a class. |
|
212 <dt>\c allmemberslink |
|
213 <dd>Represents the link to the list of all members for a class. |
|
214 <dt>\c usedfiles |
|
215 <dd>Represents the list of files from which documentation for the class was |
|
216 extracted. |
|
217 </dl> |
|
218 |
|
219 The file page has the following specific tags: |
|
220 <dl> |
|
221 <dt>\c includes |
|
222 <dd>Represents the list of \#include statements contained in this file. |
|
223 <dt>\c includegraph |
|
224 <dd>Represents the include dependency graph for the file. |
|
225 <dt>\c includedbygraph |
|
226 <dd>Represents the included by dependency graph for the file. |
|
227 <dt>\c sourcelink |
|
228 <dd>Represents the link to the source code of this file. |
|
229 </dl> |
|
230 |
|
231 The group page has a specific \c groupgraph tag which represents the |
|
232 graph showing the dependencies between groups. |
|
233 |
|
234 Similarily, the directory page has a specific \c directorygraph tag |
|
235 which represents the graph showing the dependencies between the directories |
|
236 based on the \#include relations of the files inside the directories. |
|
237 |
|
238 \section xmlgenerator Using the XML output |
|
239 |
|
240 If the above two methods still do not provide enough flexibility, you |
|
241 can also use the XML output produced by doxygen as a basis to |
|
242 generate the output you like. To do this set GENERATE_XML to YES. |
|
243 |
|
244 The XML output consists of an index file named \c index.xml which |
|
245 lists all items extracted by doxygen with references to the other XML files |
|
246 for details. The structure of the index is described by a schema file |
|
247 \c index.xsd. All other XML files are described by the schema file |
|
248 named \c compound.xsd. If you prefer one big XML file |
|
249 you can combine the index and the other files using the |
|
250 XSLT file \c combine.xslt. |
|
251 |
|
252 You can use any XML parser to parse the file or use the one that can be found |
|
253 in the \c addon/doxmlparser directory of doxygen source distribution. |
|
254 Look at \c addon/doxmlparser/include/doxmlintf.h for the interface of the |
|
255 parser and in \c addon/doxmlparser/example for examples. |
|
256 |
|
257 The advantage of using the doxmlparser is that it |
|
258 will only read the index file into memory and then only those XML |
|
259 files that you implicitly load via navigating through the index. As a |
|
260 result this works even for very large projects where reading all XML |
|
261 files as one big DOM tree would not fit into memory. |
|
262 |
|
263 */ |