1 /******************************************************************************
5 * Copyright (C) 1997-2012 by Dimitri van Heesch.
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.
13 * Documents produced by Doxygen are derivative works derived from the
14 * input used in their production; they are not affected by this license.
17 /*! \page customize Customizing the output
21 Doxygen provides various levels of customization.
22 The section \ref minor_tweaks "Minor Tweaks" discusses what to
23 do if you want to do minor tweaking to the look and feel of the output.
24 The section \ref layout "Layout" show how to reorder and hide certain
25 information on a page.
26 The section \ref xmlgenerator "XML output" show how to generate
27 whatever output you want based on the XML output produced by doxygen.
29 \section minor_tweaks Minor Tweaks
31 The next subsections describe some aspects that can be tweaked with
34 \subsection minor_tweaks_colors Overall Color
36 To change the overall color of the HTML output doxygen provides three options
37 - \ref cfg_html_colorstyle_hue "HTML_COLORSTYLE_HUE"
38 - \ref cfg_html_colorstyle_sat "HTML_COLORSTYLE_SAT"
39 - \ref cfg_html_colorstyle_gamma "HTML_COLORSTYLE_GAMMA"
41 to change the hue, saturation, and gamma correction of the colors respectively.
43 For your convenience the GUI frontend \ref doxywizard_usage "Doxywizard"
44 has a control that allows you to see the effect of changing the values of these options
45 on the output in real time.
47 \subsection minor_tweaks_treeview Navigation
49 By default doxygen shows navigation tabs on top of every HTML page,
50 corresponding with the following settings:
52 - \ref cfg_disable_index "DISABLE_INDEX" = \c NO
53 - \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c NO
55 you can switch to an interactive navigation tree as sidebar using
57 - \ref cfg_disable_index "DISABLE_INDEX" = \c YES
58 - \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c YES
60 or even have both forms of navigation:
62 - \ref cfg_disable_index "DISABLE_INDEX" = \c NO
63 - \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c YES
65 if you already use an external index (i.e. have one of the following
67 \ref cfg_generate_htmlhelp "GENERATE_HTMLHELP",
68 \ref cfg_generate_eclipsehelp "GENERATE_ECLIPSEHELP",
69 \ref cfg_generate_qhp "GENERATE_QHP", or
70 \ref cfg_generate_docset "GENERATE_DOCSET")
71 then you can also disable all indices, like so:
73 - \ref cfg_disable_index "DISABLE_INDEX" = \c YES
74 - \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c NO
76 \subsection minor_tweaks_dynsection Dynamic Content
78 To make the HTML output more interactive, doxygen provides a number of options
79 that are disabled by default:
80 - enabling \ref cfg_html_dynamic_sections "HTML_DYNAMIC_SECTIONS" will make
81 doxygen hide certain content (like graphs) in the HTML by default,
82 and let the reader expand these sections on request.
83 - enabling \ref cfg_have_dot "HAVE_DOT" along
84 with \ref cfg_interactive_svg "INTERACTIVE_SVG" while setting
85 \ref cfg_dot_image_format "DOT_IMAGE_FORMAT" to \c svg, will make doxygen
86 produce SVG images that will allow the user to zoom and pan (this only
87 happens when the size of the images exceeds a certain size).
89 \subsection minor_tweaks_header_css Header, Footer, and Stylesheet changes
91 To tweak things like fonts or colors, margins, or other look \& feel
92 aspects of the HTML output in detail, you can create a different
93 <a href="http://www.w3schools.com/css/default.asp">cascading style sheet</a>.
94 You can also let doxygen use a custom header and footer for each HTML
95 page it generates, for instance to make the output conform to the style
96 used on the rest of your web site.
98 To do this first run doxygen as follows:
100 doxygen -w html header.html footer.html customdoxygen.css
103 This will create 3 files:
104 - header.html is a HTML fragment which doxygen normally uses to start
105 a HTML page. Note that the fragment ends with a body tag and that is
106 contains a couple of commands of the form \$word. These will be replaced
107 by doxygen on the fly.
108 - footer.html is a HTML fragment which doxygen normally uses to end
109 a HTML page. Also here special commands can be used. This file contain the
110 link to www.doxygen.org and the body and html end tags.
111 - customdoxygen.css is the default cascading style sheet
114 You should edit these files and then reference them from the config file.
115 - \ref cfg_html_header "HTML_HEADER" = \c header.html
116 - \ref cfg_html_footer "HTML_FOOTER" = \c footer.html
117 - \ref cfg_html_stylesheet "HTML_STYLESHEET" = \c customdoxygen.css
119 See the documentation of the \ref cfg_html_header "HTML_HEADER" tag
120 for more information about the possible meta commands you can use inside
123 \note You should not put the style sheet in the HTML output directory. Treat
124 it as a source file. Doxygen will copy it for you.
126 \note If you use images or other external content in a custom header you
127 need to make sure these end up in the HTML output directory yourself,
128 for instance by writing a script that runs doxygen can then copies the
129 images to the output.
131 \warning The structure of headers and footers may change after upgrading to
132 a newer version of doxygen, so if you are using a custom header or footer,
133 it might not produce valid output anymore after upgrading.
135 \section layout Changing the layout of pages
137 In some cases you may want to change the way the output is structured.
138 A different style sheet or custom headers and footers do not help in such
141 The solution doxygen provides is a layout file, which you can
142 modify and doxygen will use to control what information is presented,
143 in which order, and to some extent also how information is presented.
144 The layout file is an XML file.
146 The default layout can be generated
147 by doxygen using the following command:
151 optionally the name of the layout file can be specified, if omitted
152 \c DoxygenLayout.xml will be used.
154 The next step is to mention the layout file in the config file
156 LAYOUT_FILE = DoxygenLayout.xml
158 To change the layout all you need to do is edit the layout file.
160 The toplevel structure of the file looks as follows:
162 <doxygenlayout version="1.0">
184 The root element of the XML file is \c doxygenlayout, it has an attribute named
185 \c version, which will be used in the future to cope with changes that are
186 not backward compatible.
188 The first section, identified by the \c navindex element, represents the
189 layout of the navigation tabs displayed at the top of each HTML page. At the
190 same time it also controls the items in the navigation tree in case
191 \ref cfg_generate_treeview "GENERATE_TREEVIEW" is enabled.
192 Each tab is represented by a \c tab element in the XML file.
194 You can hide tabs by setting the \c visible attribute to \c no.
195 You can also override the default title of a tab by specifying it as
196 the value of the \c title attribute. If the title field is the empty string
197 (the default) then doxygen will fill in an appropriate language specific title.
199 You can reorder the tabs by moving the tab elements in the XML file
200 within the \c navindex element and even change the tree structure.
201 Do not change the value of the \c type attribute however.
202 Only a fixed set of types are supported, each representing a link to a
205 You can also add custom tabs using a type with name "user". Here is an
206 example that shows how to add a tab with title "Google" pointing to
212 <tab type="user" url="http://www.google.com" title="Google"/>
217 The url field can also be a relative URL. If the URL starts with \@ref
218 the link will point to a documented entities, such as a class, a function,
219 a group, or a related page. Suppose we have defined a page using \@page with
220 label mypage, then a tab with label "My Page" to this page would look
226 <tab type="user" url="@ref mypage" title="My Page"/>
231 You can also group tabs together in a custom group using a tab with
232 type "usergroup". The following example puts the above tabs in a user
233 defined group with title "My Group":
238 <tab type="usergroup" title="My Group">
239 <tab type="user" url="http://www.google.com" title="Google"/>
240 <tab type="user" url="@ref mypage" title="My Page"/>
246 Groups can be nested to form a hierarchy.
248 The elements after \c navindex represent the layout of the different
249 pages generated by doxygen:
250 - The \c class element represents the layout of all pages generated for
251 documented classes, structs, unions, and interfaces.
252 - The \c namespace element represents the layout of all pages generated for
253 documented namespaces (and also Java packages).
254 - The \c file element represents the layout of all pages generated for
256 - The \c group element represents the layout of all pages generated for
257 documented groups (or modules).
258 - The \c directory element represents the layout of all pages generated for
259 documented directories.
261 Each XML element within one of the above page elements represents a certain
262 piece of information. Some pieces can appear in each type of page,
263 others are specific for a certain type of page.
264 Doxygen will list the pieces in the order in which they appear
267 The following generic elements are possible for each page:
269 <dt>\c briefdescription
270 <dd>Represents the brief description on a page.
271 <dt>\c detaileddescription
272 <dd>Represents the detailed description on a page.
274 <dd>Represents the author section of a page (only used for man pages).
276 <dd>Represents the quick overview of members on a page (member declarations).
277 This elements has child elements per type of member list.
278 The possible child elements are not listed in detail in the document,
279 but the name of the element should be a good indication of the type
280 of members that the element represents.
282 <dd>Represents the detailed member list on a page (member definition).
283 Like the \c memberdecl element, also this element has a number of
284 possible child elements.
287 The class page has the following specific elements:
290 <dd>Represents the include file needed to obtain the definition for
292 <dt>\c inheritancegraph
293 <dd>Represents the inheritance relations for a class.
294 Note that the CLASS_DIAGRAM option determines
295 if the inheritance relation is a list of base and derived classes or
297 <dt>\c collaborationgraph
298 <dd>Represents the collaboration graph for a class.
299 <dt>\c allmemberslink
300 <dd>Represents the link to the list of all members for a class.
302 <dd>Represents the list of files from which documentation for the class was
306 The file page has the following specific elements:
309 <dd>Represents the list of \#include statements contained in this file.
311 <dd>Represents the include dependency graph for the file.
312 <dt>\c includedbygraph
313 <dd>Represents the included by dependency graph for the file.
315 <dd>Represents the link to the source code of this file.
318 The group page has a specific \c groupgraph element which represents the
319 graph showing the dependencies between groups.
321 Similarly, the directory page has a specific \c directorygraph element
322 which represents the graph showing the dependencies between the directories
323 based on the \#include relations of the files inside the directories.
325 Some elements have a \c visible attribute which can be
326 used to hide the fragment from the generated output, by setting the attribute's
327 value to "no". You can also use the value of a configuration option to
328 determine the visibility, by using
329 its name prefixed with a dollar sign, e.g.
332 <includes visible="$SHOW_INCLUDE_FILES"/>
335 This was mainly added for backward compatibility.
336 Note that the \c visible attribute is just a hint for doxygen.
337 If no relevant information is available for a certain piece it is
338 omitted even if it is set to \c yes (i.e. no empty sections are generated).
340 Some elements have a \c title attribute. This attribute can be used
341 to customize the title doxygen will use as a header for the piece.
343 @warning at the moment you should not remove elements from the layout file
344 as a way to hide information. Doing so can cause broken links in the
348 \section xmlgenerator Using the XML output
350 If the above two methods still do not provide enough flexibility, you
351 can also use the XML output produced by doxygen as a basis to
352 generate the output you like. To do this set GENERATE_XML to YES.
354 The XML output consists of an index file named \c index.xml which
355 lists all items extracted by doxygen with references to the other XML files
356 for details. The structure of the index is described by a schema file
357 \c index.xsd. All other XML files are described by the schema file
358 named \c compound.xsd. If you prefer one big XML file
359 you can combine the index and the other files using the
360 XSLT file \c combine.xslt.
362 You can use any XML parser to parse the file or use the one that can be found
363 in the \c addon/doxmlparser directory of doxygen source distribution.
364 Look at \c addon/doxmlparser/include/doxmlintf.h for the interface of the
365 parser and in \c addon/doxmlparser/example for examples.
367 The advantage of using the doxmlparser is that it
368 will only read the index file into memory and then only those XML
369 files that you implicitly load via navigating through the index. As a
370 result this works even for very large projects where reading all XML
371 files as one big DOM tree would not fit into memory.
373 See <a href="https://github.com/michaeljones/breathe">the Breathe project</a> for
374 a example that uses doxygen XML output from Python to bridge it with the
375 <a href="http://sphinx.pocoo.org/">Sphinx</a> document generator.