The section discusses how to adjust various tags in the project file to change the look of the generated documentation.

Colors

To change the colors of the HTML output alter the following three options to change the hue, saturation, and gamma correction of the colors. DoxyPressApp has a control which allows you to view the effect of changing the values of these options on the output in real time.

Navigation

By default the navigation tabs will appear on the top of every HTML page, corresponding to the following tag settings:

disable-index = NO
generate-treeview = NO

You can switch to an interactive navigation tree as sidebar using the following tag settings:

disable-index = YES
generate-treeview = YES

To have both forms of navigation use the following tag settings:

disable-index = NO
generate-treeview = YES

If you created an external index or have one of the following options enabled,

generate-chm, generate-eclipse generate-qthelp generate-docset

then you may want to disable all index files as follows:

disable-index = YES
generate-treeview = NO

Dynamic Content

To make the HTML output more interactive DoxyPress provides a number of options which are disabled by default:

Enabling html-dynamic-sections will make certain content like graphs in the HTML by default, and let the reader expand these sections on request.
Enabling have-dot along with interactive-svg while setting dot-image-format to svg, will produce SVG images which will allow the user to zoom and pan. This only happens when the size of the images exceeds a certain size.

Custom Styling

Fonts, colors, margins, and other aspects of the HTML output can be modified by adding one or more custom CSS or stylesheet files. For details about how to generate the DoxyPress default files ref to Headers, Footers, Stylesheets.

Header: Default generated name is doxy_header.html; An HTML file which DoxyPress uses to start an HTML page; File ends with a body tag; Contains commands in the form $word, which will be replaced by DoxyPress; Refer to html-header for more information
Footer: Default generated name is doxy_footer.html; An HTML file which DoxyPress uses to end an HTML page; Contains commands in the form $word, which will be replaced by DoxyPress; Refer to html-footer for more information
Stylesheet: Default generated name is doxypress.css; If you want to override the values in the default file, create a new CSS file and include the name in the html-stylesheets tag in your project; Refer to html-footer for more information

If you use images or other external content in a custom header, ensure these files are in the HTML output directory. For example, writ a script which runs DoxyPress and then copies the images to the output directory.

Layout

The Layout file controls the structure of the documentation. To change the output structure the sections can be rearranged and the section titles can be modified. If a section should be omitted change the visible attribute to no. Do not delete elements in this file.

This file controls what information is presented, in which order, the navigation section title names, etc. The layout file is an XML file.

For details about how to generate the DoxyPress default layout file ref to Layout File.

The layout file name must be specified in your project file so DoxyPress will know to override the internal layout file. The project tag to change is layout-file.

Layout Details

The first section of the layout file is the <navindex> element. This section represents the layout of the navigation tabs displayed at the top of each HTML page. It also controls the items in the navigation tree if generate-treeview is enabled. Each tab is represented by a tab element.

Tabs can be hidden by setting the visible attribute to NO.

You can override the default title of a tab by specifying it as the value of the title attribute. If the title field is empty then DoxyPress will fill in an appropriate language specific title.

Do not change the value of the type attribute.

Tabs can be reorder by moving the tab elements in the XML file within the navindex element. Only a fixed set of tab types are supported, each representing a link to a specific index.

You can also add custom tabs using a type with name "user". The following is an example which shows how to add a tab with title "Google" pointing to www.google.com:

  <navindex>
    ...
    <tab type="user" url="https://www.google.com" title="Google"/>
    ...
  </navindex>

The url field can be a relative URL. If the URL starts with @ref the link will point to documented entities, such as a class, function, group, or a related page. Suppose we have defined a page using @page with label mypage and a tab with label "My Page". The xml would look like the following:

  <navindex>
    ...
    <tab type="user" url="@ref mypage" title="My Page"/>
    ...
  </navindex>

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":

  <navindex>
    ...
    <tab type="usergroup" title="My Group">
      <tab type="user" url="https://www.google.com" title="Google"/>
      <tab type="user" url="@ref mypage" title="My Page"/>
    </tab>
    ...
  </navindex>

Groups can be nested to form a hierarchy.

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 url attribute just like you can for the <tab> element and prevent any link using url="[none]".

   <tab type="usergroup" title="Group without link" url="[none]">
   ...
   </tab>

The elements after the navindex section represent the layout of the different pages generated by DoxyPress.

The class element represents the layout of all pages generated for documented classes, structs, unions, and interfaces.
The namespace element represents the layout of all pages generated for documented namespaces (and also Java packages).
The file element represents the layout of all pages generated for documented files.
The group element represents the layout of all pages generated for documented groups (or modules).
The directory element represents the layout of all pages generated for documented directories.

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. DoxyPress will list the sections in the order in which they appear in the XML file.

The following generic elements are possible for each page:

briefdescription: Represents the brief description on a page
detaileddescription: Represents the detailed description on a page
authorsection: Represents the author section of a page, only used for man output
memberdecl: 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.
memberdef: Represents the detailed member list on a page (member definition). Like the memberdecl element, also this element has a number of possible child elements.

The class page has the following specific elements:

includes: Represents the include file needed to obtain the definition for this class
inheritancegraph: Represents the inheritance relations for a class. The CLASS-DIAGRAM tag determines if the inheritance relation is a list of base and derived classes or a graph.
collaborationgraph: Represents the collaboration graph for a class
allmemberslink: Represents the link to the list of all members for a class
usedfiles: Represents the list of files from which documentation for the class was extracted

The file page has the following specific elements:

includes: Represents the list of #include statements contained in this file
includegraph: Represents the include dependency graph for the file
includedbygraph: Represents the included by dependency graph for the file
sourcelink: Represents the link to the source code of this file

The group page has a specific groupgraph element which represents the graph showing the dependencies between groups.

The directory page has a specific directorygraph element which represents the graph showing the dependencies between the directories based on the #include relations of the files inside the directories.

Some XML elements have a visible attribute which can be used to hide the fragment from the generated output. This is done by setting the attribute value to "no".

Alternatively, set the visible attribute in your layout file file to the name of a project file tag prefixed with a dollar sign.

  ...
  <includes visible="$SHOW-INCLUDE-FILES"/>
  ...

Some elements have a title attribute. This attribute can be used to customize the title DoxyPress will use as a header for the fragment

Warning: Do not remove elements from the layout file as this can cause broken links in the generated output.

XML output

You can also use the XML output produced by DoxyPress as a basis to generate the output you like. To do this set GENERATE-XML to YES.

The XML output consists of an index file named index.xml which lists all items extracted by DoxyPress with references to the other XML files for details. The structure of the index is described by a schema file index.xsd. All other XML files are described by the schema file named compound.xsd. If you prefer one big XML file you can combine the index and the other files using the XSLT file combine.xslt.

You can use any XML parser to parse the file or use the parser released with DoxyPress. The file is called doxmlparser. Review the file doxmlintf.h for the interface of the parser.

The advantage of using the doxmlparser is that it will only read the index file into memory and then only those XML files 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 large DOM tree would not fit into memory.