diff options
Diffstat (limited to 'doc/customize.doc')
| -rw-r--r-- | doc/customize.doc | 238 |
1 files changed, 174 insertions, 64 deletions
diff --git a/doc/customize.doc b/doc/customize.doc index 1a8b3dd..d1be915 100644 --- a/doc/customize.doc +++ b/doc/customize.doc @@ -17,21 +17,83 @@ /*! \page customize Customizing the output Doxygen provides various levels of customization. -The \ref minor_tweaks "first section" discusses what to +The section \ref minor_tweaks "Minor Tweaks" discusses what to do if you want to do minor tweaking to the look and feel of the output. -The \ref layout "next" section show how to reorder and hide certain +The section \ref layout "Layout" show how to reorder and hide certain information on a page. -The \ref xmlgenerator "last" section show how to generate whatever output -you want based on the XML output produced by doxygen. +The section \ref xmlgenerator "XML output" show how to generate +whatever output you want based on the XML output produced by doxygen. \section minor_tweaks Minor Tweaks -To simply tweak things like fonts or colors, margins, or other look \& feel -expects of the HTML output you can create a different +The next subsections describe some aspects that can be tweaked with +little effort. + +\subsection minor_tweaks_colors Overall Color + +To change the overall color of the HTML output doxygen provides three options +- \ref cfg_html_colorstyle_hue "HTML_COLORSTYLE_HUE" +- \ref cfg_html_colorstyle_sat "HTML_COLORSTYLE_SAT" +- \ref cfg_html_colorstyle_gamma "HTML_COLORSTYLE_GAMMA" + +to change the hue, saturation, and gamma correction of the colors respectively. + +For your convenience the GUI frontend \ref doxywizard_usage "Doxywizard" +has a control that allows you to see the effect of changing the values of these options +on the output in real time. + +\subsection minor_tweaks_treeview Navigation + +By default doxygen shows navigation tabs on top of every HTML page, +corresponding with the following settings: + +- \ref cfg_disable_index "DISABLE_INDEX" = \c NO +- \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c NO + +you can switch to an interactive navigation tree as sidebar using + +- \ref cfg_disable_index "DISABLE_INDEX" = \c YES +- \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c YES + +or even have both forms of navigation: + +- \ref cfg_disable_index "DISABLE_INDEX" = \c NO +- \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c YES + +if you already use an external index (i.e. have one of the following +options enabled +\ref cfg_generate_htmlhelp "GENERATE_HTMLHELP", +\ref cfg_generate_eclipsehelp "GENERATE_ECLIPSEHELP", +\ref cfg_generate_qhp "GENERATE_QHP", or +\ref cfg_generate_docset "GENERATE_DOCSET") +then you can also disable all indices, like so: + +- \ref cfg_disable_index "DISABLE_INDEX" = \c YES +- \ref cfg_generate_treeview "GENERATE_TREEVIEW" = \c NO + +\subsection minor_tweaks_dynsection Dynamic Content + +To make the HTML output more interactive, doxygen provides a number of options +that are disabled by default: +- enabling \ref cfg_html_dynamic_sections "HTML_DYNAMIC_SECTIONS" will make + doxygen hide certain content (like graphs) in the HTML by default, + and let the reader expand these sections on request. +- enabling \ref cfg_use_inline_trees "USE_INLINE_TREES" will make some + tree structures in the output dynamically expandable. +- enabling \ref cfg_have_dot "HAVE_DOT" along + with \ref cfg_interactive_svg "INTERACTIVE_SVG" while setting + \ref cfg_dot_image_format "DOT_IMAGE_FORMAT" to \c svg, will make doxygen + produce SVG images that will allow the user to zoom and pan (this only + happens when th size of the images exceeds a certain size). + +\subsection minor_tweaks_header_css Header, Footer, and Stylesheet changes + +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 include a logo or to make the -doxygen output blend in with the rest of the web site. +page it generates, for instance to make the output comform to the style +used on the rest of your web site. To do this first run doxygen as follows: \verbatim @@ -50,14 +112,13 @@ This will create 3 files: used by doxygen. You should edit these files and then reference them from the config file. -\verbatim -HTML_HEADER = header.html -HTML_FOOTER = footer.html -HTML_STYLESHEET = customdoxygen.css -\endverbatim +- \ref cfg_html_header "HTML_HEADER" = \c header.html +- \ref cfg_html_footer "HTML_FOOTER" = \c footer.html +- \ref cfg_html_stylesheet "HTML_STYLESHEET" = \c customdoxygen.css See the documentation of the \ref cfg_html_header "HTML_HEADER" tag -for more information about the possible meta commands. +for more information about the possible meta commands you can use inside +your custom header. \note You should not put the style sheet in the HTML output directory. Treat it is a source file. Doxygen will copy it for you. @@ -67,7 +128,6 @@ 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. - \section layout Changing the layout of pages In some cases you may want to change the way the output is structured. @@ -91,7 +151,7 @@ The next step is to mention the layout file in the config file \verbatim LAYOUT_FILE = DoxygenLayout.xml \endverbatim -The change the layout all you need to do is edit the layout file. +To change the layout all you need to do is edit the layout file. The toplevel structure of the file looks as follows: \verbatim @@ -117,66 +177,90 @@ The toplevel structure of the file looks as follows: </doxygenlayout> \endverbatim -The root tag of the XML is \c doxygenlayout, it has an attribute named +The root element of the XML file is \c doxygenlayout, it has an attribute named \c version, which will be used in the future to cope with changes that are not backward compatible. -The first section, enclosed by \c navindex tags represents the layout of -the navigation tabs displayed at the top of each HTML page. -Each tab is represented by a \c tab tag in the XML file. +The first section, identified by the \c navindex 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 +\ref cfg_generate_treeview "GENERATE_TREEVIEW" is enabled. +Each tab is represented by a \c tab element in the XML file. You can hide tabs by setting the \c visible attribute to \c no. You can also override the default title of a tab by specifying it as the value of the \c title attribute. If the title field is the empty string -(the default) then doxygen will fill in an appropriate title. -You can reorder the tabs by moving the tab tags in the XML file -within the \c navindex section and even change the tree structure. +(the default) then doxygen will fill in an appropriate language specific title. + +You can reorder the tabs by moving the tab elements in the XML file +within the \c navindex element and even change the tree structure. Do not change the value of the \c type attribute however. Only a fixed set of types are supported, each representing a link to a specific index. -The sections after \c navindex represent the layout of the different +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: + +\verbatim + <navindex> + ... + <tab type="user" url="http://www.google.com" title="Google"/> + ... + </navindex> +\endverbatim + +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: + +\verbatim + <navindex> + ... + <tab type="user" url="@ref mypage" title="My Page"/> + ... + </navindex> +\endverbatim + +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": + +\verbatim + <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> +\endverbatim + +Groups can be nested to form a hierarchy. + +The elements after \c navindex represent the layout of the different pages generated by doxygen: -- The \c class section represents the layout of all pages generated for +- The \c class element represents the layout of all pages generated for documented classes, structs, unions, and interfaces. -- The \c namespace section represents the layout of all pages generated for +- The \c namespace element represents the layout of all pages generated for documented namespaces (and also Java packages). -- The \c file section represents the layout of all pages generated for +- The \c file element represents the layout of all pages generated for documented files. -- The \c group section represents the layout of all pages generated for +- The \c group element represents the layout of all pages generated for documented groups (or modules). -- The \c directory section represents the layout of all pages generated for +- The \c directory element represents the layout of all pages generated for documented directories. -Each XML tag within one of the above page sections represents a certain +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. -Some tags have a \c visible 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. -\verbatim - ... - <includes visible="$SHOW_INCLUDE_FILES"/> - ... -\endverbatim -This was mainly added for backward compatibility. -Note that the \c visible 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 \c yes (i.e. no empty sections are generated). - -Some tags have a \c title attribute. This attribute can be used -to customize the title doxygen will use as a header for the piece. - -@warning at the moment you should not remove tags from the layout file -as a way to hide information. Doing so can cause broken links in the -generated output! - -At the moment the following generic tags are possible for each page: +The following generic elements are possible for each page: <dl> <dt>\c briefdescription <dd>Represents the brief description on a page. @@ -186,18 +270,17 @@ At the moment the following generic tags are possible for each page: <dd>Represents the author section of a page (only used for man pages). <dt>\c memberdecl <dd>Represents the quick overview of members on a page (member declarations). - This tag has child tags each representing a list of - members of a certain type. - The possible child tags are not listed in detail in the document, - but the name of the tag should be a good indication of the type - of members that the tag represents. + 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. <dt>\c memberdef <dd>Represents the detailed member list on a page (member definition). - Like the \c memberdecl tag, also this tag has a number of - possible child tags. + Like the \c memberdecl element, also this element has a number of + possible child elements. </dl> -The class page has the following specific tags: +The class page has the following specific elements: <dl> <dt>\c includes <dd>Represents the include file needed to obtain the definition for @@ -216,7 +299,7 @@ The class page has the following specific tags: extracted. </dl> -The file page has the following specific tags: +The file page has the following specific elements: <dl> <dt>\c includes <dd>Represents the list of \#include statements contained in this file. @@ -228,13 +311,36 @@ The file page has the following specific tags: <dd>Represents the link to the source code of this file. </dl> -The group page has a specific \c groupgraph tag which represents the +The group page has a specific \c groupgraph element which represents the graph showing the dependencies between groups. -Similarly, the directory page has a specific \c directorygraph tag +Similarly, the directory page has a specific \c directorygraph element which represents the graph showing the dependencies between the directories based on the \#include relations of the files inside the directories. +Some elements have a \c visible 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. +\verbatim + ... + <includes visible="$SHOW_INCLUDE_FILES"/> + ... +\endverbatim +This was mainly added for backward compatibility. +Note that the \c visible 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 \c yes (i.e. no empty sections are generated). + +Some elements have a \c title attribute. This attribute can be used +to customize the title doxygen will use as a header for the piece. + +@warning 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! + + \section xmlgenerator Using the XML output If the above two methods still do not provide enough flexibility, you @@ -260,4 +366,8 @@ 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. +See <a href="https://github.com/michaeljones/breathe">the Breathe project</a> for +a example that uses doxygen XML output from Python to bridge it with the +<a href="http://sphinx.pocoo.org/">Sphinx</a> document generator. + */ |