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
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.12"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Doxygen: Customizing the output</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
$(document).ready(initResizable);
</script>
<link href="doxygen_manual.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">Doxygen
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.12 -->
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('customize.html','');});
</script>
<div id="doc-content">
<div class="header">
<div class="headertitle">
<div class="title">Customizing the output </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#minor_tweaks">Minor Tweaks</a><ul><li class="level2"><a href="#minor_tweaks_colors">Overall Color</a></li>
<li class="level2"><a href="#minor_tweaks_treeview">Navigation</a></li>
<li class="level2"><a href="#minor_tweaks_dynsection">Dynamic Content</a></li>
<li class="level2"><a href="#minor_tweaks_header_css">Header, Footer, and Stylesheet changes</a></li>
</ul>
</li>
<li class="level1"><a href="#layout">Changing the layout of pages</a></li>
<li class="level1"><a href="#xmlgenerator">Using the XML output</a></li>
</ul>
</div>
<div class="textblock"><p>Doxygen provides various levels of customization. The section <a class="el" href="customize.html#minor_tweaks">Minor Tweaks</a> discusses what to do if you want to do minor tweaking to the look and feel of the output. The section <a class="el" href="customize.html#layout">Layout</a> show how to reorder and hide certain information on a page. The section <a class="el" href="customize.html#xmlgenerator">XML output</a> show how to generate whatever output you want based on the XML output produced by doxygen.</p>
<h1><a class="anchor" id="minor_tweaks"></a>
Minor Tweaks</h1>
<p>The next subsections describe some aspects that can be tweaked with little effort.</p>
<h2><a class="anchor" id="minor_tweaks_colors"></a>
Overall Color</h2>
<p>To change the overall color of the HTML output doxygen provides three options</p><ul>
<li><a class="el" href="config.html#cfg_html_colorstyle_hue">HTML_COLORSTYLE_HUE</a></li>
<li><a class="el" href="config.html#cfg_html_colorstyle_sat">HTML_COLORSTYLE_SAT</a></li>
<li><a class="el" href="config.html#cfg_html_colorstyle_gamma">HTML_COLORSTYLE_GAMMA</a></li>
</ul>
<p>to change the hue, saturation, and gamma correction of the colors respectively.</p>
<p>For your convenience the GUI frontend <a class="el" href="doxywizard_usage.html">Doxywizard</a> has a control that allows you to see the effect of changing the values of these options on the output in real time.</p>
<h2><a class="anchor" id="minor_tweaks_treeview"></a>
Navigation</h2>
<p>By default doxygen shows navigation tabs on top of every HTML page, corresponding with the following settings:</p>
<ul>
<li><a class="el" href="config.html#cfg_disable_index">DISABLE_INDEX</a> = <code>NO</code> </li>
<li><a class="el" href="config.html#cfg_generate_treeview">GENERATE_TREEVIEW</a> = <code>NO</code> </li>
</ul>
<p>you can switch to an interactive navigation tree as sidebar using</p>
<ul>
<li><a class="el" href="config.html#cfg_disable_index">DISABLE_INDEX</a> = <code>YES</code> </li>
<li><a class="el" href="config.html#cfg_generate_treeview">GENERATE_TREEVIEW</a> = <code>YES</code> </li>
</ul>
<p>or even have both forms of navigation:</p>
<ul>
<li><a class="el" href="config.html#cfg_disable_index">DISABLE_INDEX</a> = <code>NO</code> </li>
<li><a class="el" href="config.html#cfg_generate_treeview">GENERATE_TREEVIEW</a> = <code>YES</code> </li>
</ul>
<p>if you already use an external index (i.e. have one of the following options enabled <a class="el" href="config.html#cfg_generate_htmlhelp">GENERATE_HTMLHELP</a>, <a class="el" href="config.html#cfg_generate_eclipsehelp">GENERATE_ECLIPSEHELP</a>, <a class="el" href="config.html#cfg_generate_qhp">GENERATE_QHP</a>, or <a class="el" href="config.html#cfg_generate_docset">GENERATE_DOCSET</a>) then you can also disable all indices, like so:</p>
<ul>
<li><a class="el" href="config.html#cfg_disable_index">DISABLE_INDEX</a> = <code>YES</code> </li>
<li><a class="el" href="config.html#cfg_generate_treeview">GENERATE_TREEVIEW</a> = <code>NO</code> </li>
</ul>
<h2><a class="anchor" id="minor_tweaks_dynsection"></a>
Dynamic Content</h2>
<p>To make the HTML output more interactive, doxygen provides a number of options that are disabled by default:</p><ul>
<li>enabling <a class="el" href="config.html#cfg_html_dynamic_sections">HTML_DYNAMIC_SECTIONS</a> will make doxygen hide certain content (like graphs) in the HTML by default, and let the reader expand these sections on request.</li>
<li>enabling <a class="el" href="config.html#cfg_have_dot">HAVE_DOT</a> along with <a class="el" href="config.html#cfg_interactive_svg">INTERACTIVE_SVG</a> while setting <a class="el" href="config.html#cfg_dot_image_format">DOT_IMAGE_FORMAT</a> to <code>svg</code>, will make doxygen produce SVG images that will allow the user to zoom and pan (this only happens when the size of the images exceeds a certain size).</li>
</ul>
<h2><a class="anchor" id="minor_tweaks_header_css"></a>
Header, Footer, and Stylesheet changes</h2>
<p>To tweak things like fonts or colors, margins, or other look & feel aspects of the HTML output in detail, you can create a different <a href="http://www.w3schools.com/css/default.asp">cascading style sheet</a>. You can also let doxygen use a custom header and footer for each HTML page it generates, for instance to make the output conform to the style used on the rest of your web site.</p>
<p>To do this first run doxygen as follows: </p><pre class="fragment">doxygen -w html header.html footer.html customdoxygen.css
</pre><p>This will create 3 files:</p><ul>
<li>header.html is a HTML fragment which doxygen normally uses to start a HTML page. Note that the fragment ends with a body tag and that is contains a couple of commands of the form $word. These will be replaced by doxygen on the fly.</li>
<li>footer.html is a HTML fragment which doxygen normally uses to end a HTML page. Also here special commands can be used. This file contain the link to www.doxygen.org and the body and html end tags.</li>
<li>customdoxygen.css is the default cascading style sheet used by doxygen. It is recommended only to look into this file and overrule some settings you like by putting them in a separate stylesheets and referencing those extra files via <a class="el" href="config.html#cfg_html_extra_stylesheet">HTML_EXTRA_STYLESHEET</a>.</li>
</ul>
<p>You should edit these files and then reference them from the config file.</p><ul>
<li><a class="el" href="config.html#cfg_html_header">HTML_HEADER</a> = <code>header.html</code> </li>
<li><a class="el" href="config.html#cfg_html_footer">HTML_FOOTER</a> = <code>footer.html</code> </li>
<li><a class="el" href="config.html#cfg_html_extra_stylesheet">HTML_EXTRA_STYLESHEET</a> = <code>my_customdoxygen.css</code> </li>
</ul>
<dl class="section note"><dt>Note</dt><dd>it is not longer recommended to use <a class="el" href="config.html#cfg_html_stylesheet">HTML_STYLESHEET</a>, as it make it difficult to upgrade to a newer version of doxygen. Use <a class="el" href="config.html#cfg_html_extra_stylesheet">HTML_EXTRA_STYLESHEET</a> instead.</dd></dl>
<p>See the documentation of the <a class="el" href="config.html#cfg_html_header">HTML_HEADER</a> tag for more information about the possible meta commands you can use inside your custom header.</p>
<dl class="section note"><dt>Note</dt><dd>You should not put the style sheet in the HTML output directory. Treat it as a source file. Doxygen will copy it for you.</dd>
<dd>
If you use images or other external content in a custom header you need to make sure these end up in the HTML output directory yourself, for instance by writing a script that runs doxygen can then copies the images to the output.</dd></dl>
<dl class="section warning"><dt>Warning</dt><dd>The structure of headers and footers may change after upgrading to a newer version of doxygen, so if you are using a custom header or footer, it might not produce valid output anymore after upgrading.</dd></dl>
<h1><a class="anchor" id="layout"></a>
Changing the layout of pages</h1>
<p>In some cases you may want to change the way the output is structured. A different style sheet or custom headers and footers do not help in such case.</p>
<p>The solution doxygen provides is a layout file, which you can modify and doxygen will use to control what information is presented, in which order, and to some extent also how information is presented. The layout file is an XML file.</p>
<p>The default layout can be generated by doxygen using the following command: </p><pre class="fragment">doxygen -l
</pre><p> optionally the name of the layout file can be specified, if omitted <code>DoxygenLayout.xml</code> will be used.</p>
<p>The next step is to mention the layout file in the config file </p><pre class="fragment">LAYOUT_FILE = DoxygenLayout.xml
</pre><p> To change the layout all you need to do is edit the layout file.</p>
<p>The toplevel structure of the file looks as follows: </p><pre class="fragment"><doxygenlayout version="1.0">
<navindex>
...
</navindex>
<class>
...
</class>
<namespace>
...
</namespace>
<file>
...
</file>
<group>
...
</group>
<directory>
...
</directory>
</doxygenlayout>
</pre><p>The root element of the XML file is <code>doxygenlayout</code>, it has an attribute named <code>version</code>, which will be used in the future to cope with changes that are not backward compatible.</p>
<p>The first section, identified by the <code>navindex</code> element, represents the layout of the navigation tabs displayed at the top of each HTML page. At the same time it also controls the items in the navigation tree in case <a class="el" href="config.html#cfg_generate_treeview">GENERATE_TREEVIEW</a> is enabled. Each tab is represented by a <code>tab</code> element in the XML file.</p>
<p>You can hide tabs by setting the <code>visible</code> attribute to <code>no</code>. You can also override the default title of a tab by specifying it as the value of the <code>title</code> attribute. If the title field is the empty string (the default) then doxygen will fill in an appropriate language specific title.</p>
<p>You can reorder the tabs by moving the tab elements in the XML file within the <code>navindex</code> element and even change the tree structure. Do not change the value of the <code>type</code> attribute however. Only a fixed set of types are supported, each representing a link to a specific index.</p>
<p>You can also add custom tabs using a type with name "user". Here is an example that shows how to add a tab with title "Google" pointing to www.google.com:</p>
<pre class="fragment"> <navindex>
...
<tab type="user" url="http://www.google.com" title="Google"/>
...
</navindex>
</pre><p>The url field can also be a relative URL. If the URL starts with @ref the link will point to a documented entities, such as a class, a function, a group, or a related page. Suppose we have defined a page using @page with label mypage, then a tab with label "My Page" to this page would look as follows:</p>
<pre class="fragment"> <navindex>
...
<tab type="user" url="@ref mypage" title="My Page"/>
...
</navindex>
</pre><p>You can also group tabs together in a custom group using a tab with type "usergroup". The following example puts the above tabs in a user defined group with title "My Group":</p>
<pre class="fragment"> <navindex>
...
<tab type="usergroup" title="My Group">
<tab type="user" url="http://www.google.com" title="Google"/>
<tab type="user" url="@ref mypage" title="My Page"/>
</tab>
...
</navindex>
</pre><p>Groups can be nested to form a hierarchy.</p>
<p>By default a usergroup entry in the navigation tree is a link to a landing page with the contents of the group. You can link to a different page using the <code>url</code> attribute just like you can for the <code><tab></code> element and prevent any link using <code>url="[none]"</code>, i.e.</p>
<pre class="fragment"> <tab type="usergroup" title="Group without link" url="[none]">
...
</tab>
</pre><p>The elements after <code>navindex</code> represent the layout of the different pages generated by doxygen:</p><ul>
<li>The <code>class</code> element represents the layout of all pages generated for documented classes, structs, unions, and interfaces.</li>
<li>The <code>namespace</code> element represents the layout of all pages generated for documented namespaces (and also Java packages).</li>
<li>The <code>file</code> element represents the layout of all pages generated for documented files.</li>
<li>The <code>group</code> element represents the layout of all pages generated for documented groups (or modules).</li>
<li>The <code>directory</code> element represents the layout of all pages generated for documented directories.</li>
</ul>
<p>Each XML element within one of the above page elements represents a certain piece of information. Some pieces can appear in each type of page, others are specific for a certain type of page. Doxygen will list the pieces in the order in which they appear in the XML file.</p>
<p>The following generic elements are possible for each page: </p><dl>
<dt><code>briefdescription</code> </dt>
<dd>Represents the brief description on a page. </dd>
<dt><code>detaileddescription</code> </dt>
<dd>Represents the detailed description on a page. </dd>
<dt><code>authorsection</code> </dt>
<dd>Represents the author section of a page (only used for man pages). </dd>
<dt><code>memberdecl</code> </dt>
<dd>Represents the quick overview of members on a page (member declarations). This elements has child elements per type of member list. The possible child elements are not listed in detail in the document, but the name of the element should be a good indication of the type of members that the element represents. </dd>
<dt><code>memberdef</code> </dt>
<dd>Represents the detailed member list on a page (member definition). Like the <code>memberdecl</code> element, also this element has a number of possible child elements. </dd>
</dl>
<p>The class page has the following specific elements: </p><dl>
<dt><code>includes</code> </dt>
<dd>Represents the include file needed to obtain the definition for this class. </dd>
<dt><code>inheritancegraph</code> </dt>
<dd>Represents the inheritance relations for a class. Note that the CLASS_DIAGRAM option determines if the inheritance relation is a list of base and derived classes or a graph. </dd>
<dt><code>collaborationgraph</code> </dt>
<dd>Represents the collaboration graph for a class. </dd>
<dt><code>allmemberslink</code> </dt>
<dd>Represents the link to the list of all members for a class. </dd>
<dt><code>usedfiles</code> </dt>
<dd>Represents the list of files from which documentation for the class was extracted. </dd>
</dl>
<p>The file page has the following specific elements: </p><dl>
<dt><code>includes</code> </dt>
<dd>Represents the list of #include statements contained in this file. </dd>
<dt><code>includegraph</code> </dt>
<dd>Represents the include dependency graph for the file. </dd>
<dt><code>includedbygraph</code> </dt>
<dd>Represents the included by dependency graph for the file. </dd>
<dt><code>sourcelink</code> </dt>
<dd>Represents the link to the source code of this file. </dd>
</dl>
<p>The group page has a specific <code>groupgraph</code> element which represents the graph showing the dependencies between groups.</p>
<p>Similarly, the directory page has a specific <code>directorygraph</code> element which represents the graph showing the dependencies between the directories based on the #include relations of the files inside the directories.</p>
<p>Some elements have a <code>visible</code> attribute which can be used to hide the fragment from the generated output, by setting the attribute's value to "no". You can also use the value of a configuration option to determine the visibility, by using its name prefixed with a dollar sign, e.g. </p><pre class="fragment"> ...
<includes visible="$SHOW_INCLUDE_FILES"/>
...
</pre><p> This was mainly added for backward compatibility. Note that the <code>visible</code> attribute is just a hint for doxygen. If no relevant information is available for a certain piece it is omitted even if it is set to <code>yes</code> (i.e. no empty sections are generated).</p>
<p>Some elements have a <code>title</code> attribute. This attribute can be used to customize the title doxygen will use as a header for the piece.</p>
<dl class="section warning"><dt>Warning</dt><dd>at the moment you should not remove elements from the layout file as a way to hide information. Doing so can cause broken links in the generated output!</dd></dl>
<h1><a class="anchor" id="xmlgenerator"></a>
Using the XML output</h1>
<p>If the above two methods still do not provide enough flexibility, you can also use the XML output produced by doxygen as a basis to generate the output you like. To do this set GENERATE_XML to YES.</p>
<p>The XML output consists of an index file named <code>index.xml</code> which lists all items extracted by doxygen with references to the other XML files for details. The structure of the index is described by a schema file <code>index.xsd</code>. All other XML files are described by the schema file named <code>compound.xsd</code>. If you prefer one big XML file you can combine the index and the other files using the XSLT file <code>combine.xslt</code>.</p>
<p>You can use any XML parser to parse the file or use the one that can be found in the <code>addon/doxmlparser</code> directory of doxygen source distribution. Look at <code>addon/doxmlparser/include/doxmlintf.h</code> for the interface of the parser and in <code>addon/doxmlparser/example</code> for examples.</p>
<p>The advantage of using the doxmlparser is that it will only read the index file into memory and then only those XML files that you implicitly load via navigating through the index. As a result this works even for very large projects where reading all XML files as one big DOM tree would not fit into memory.</p>
<p>See <a href="https://github.com/michaeljones/breathe">the Breathe project</a> for an example that uses doxygen XML output from Python to bridge it with the <a href="http://sphinx.pocoo.org/">Sphinx</a> document generator.</p>
<p>
Go to the <a href="custcmd.html">next</a> section or return to the
<a href="index.html">index</a>.
</p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.12 </li>
</ul>
</div>
</body>
</html>
|
