Norserium March 7, 2015 at 21:54

Documentation at Doxygen

This article is part of the resulting series of articles on the Doxygen documentation system:

This is the second article from the mentioned cycle, which followed the introductory article on the Doxygen documentation system (if you are not familiar with this system, I advise you to pay attention to this article and get acquainted with it at least in general terms). In the comments to it, an important question was raised about the design of documentation in Doxygen, and this issue is relevant, since the standard design is often used, which, although practical, but rather plain-looking.

In this article, I will answer this question. To do this, we will look at the general principles of Doxygen documentation, get to know them, and look at examples of what can be achieved based on them.

Customizing the look of the documentation

First, consider what functionality Doxygen provides for customizing the layout (in this case, you should pay attention to the fact that basically the settings described below relate specifically to the generated HTML document). In general, this section is described in detail in the official documentation , I will note only the main details in it and dilute it with examples for clarity.

Design Settings

Icon for the project

The simplest thing that you can customize in the design is the project icon. To do this, specify the path to the icon in the settings file in the PROJECT_LOGO option :

PROJECT_LOGO = <путь_к_иконке>

Color scheme

In order to simply change the color scheme of the HTML page, the following options are used in the settings file:

Option	Value
HTML_COLORSTYLE_HUE	Indicates the color scheme tone.
HTML_COLORSTYLE_SAT	Indicates the brightness of the color scheme.
HTML_COLORSTYLE_GAMMA	Indicates the gamut of the color scheme.

Below are examples of the same documentation with different color scheme settings:

Navigation aids

The main navigation tools for documentation in Doxygen are: tabbed menus and hierarchical tree. They are presented below in the screenshot.

To configure the display of these elements, use the following options in the settings file:

Option	Value
DISABLE_INDEX	Disables tab menu display
GENERATE_TREEVIEW	Shows whether or not to display a hierarchical tree

Dynamic documentation content

To make HTML documentation more interactive, Doxygen provides a number of options that are disabled by default:

Option	Value
HTML_DYNAMIC_SECTIONS	If this option is set, Doxygen will collapse certain elements of the HTML documentation (for example, columns), which the user can subsequently expand
INTERACTIVE_SVG	If graphing using Graphviz is enabled and SVG is specified as the graphing format, Doxygen will create interactive SVG files that can be expanded and moved

Header, footer and cascading style sheet

To customize fonts, colors, indents and other details of the HTML documentation, you can change the standard cascading style sheet. In addition, Doxygen allows you to change the title and footer for each HTML page that it generates, for example, so that the generated documentation matches the external style of the rest of your site.

In order to get the appropriate files for further editing, run the command:

doxygen -w html header.html footer.html customdoxygen.css

She will create three files:

header.html is an HTML snippet that Doxygen uses to start an HTML page. Please note that this fragment contains a couple of special commands starting with a dollar sign: they will be automatically replaced when creating documentation;
footer.html is the HTML snippet that Doxygen uses to complete the HTML page. There may also be special teams that were mentioned earlier;
customdoxygen.css is the default cascading style sheet. It is recommended only to look at this file and change certain settings by placing them in a separate file.

After you edit these files, you need to tell Doxygen to use them when building the documentation, instead of the standard files. This is done using the following commands:

Option	Value
HTML_HEADER	Specifies the path to the custom HTML file that describes the header (in the example above, this is the path to header.html)
HTML_FOOTER	Specifies the path to a custom HTML file describing the footer (in the example above, this is the path to footer.html)
HTML_EXTRA_STYLESHEET	Specifies the path to a custom cascading style sheet. Please note that it will be used along with the standard stylesheet and therefore it is sufficient to describe only what you changed in it

Design change example

Next, we will consider beautiful examples of various styles and design decisions, but for now, we will just show for self-confidence how we can change the style.

Let's make the documentation title bold for example and change its colors. To do this, create a style.css stylesheet with the following contents (projectname is the id of the block with the project name, you can verify this by opening the same header.html file):

#projectname {
	color: #3B5588;
	font-weight: bold;
}

After that, in the settings file, in the HTML_EXTRA_STYLESHEET option , specify the path to the created file and create the documentation. The result will be as follows (the previous option is shown for comparison):

In the same way, you can change the style of everything else, so go for it!

Setting up the documentation structure

Previously, we examined how you can change the appearance of the documentation, however, changing it will not affect the structure of the documentation, there is another approach for changing it.

To do this, use a special file that describes the structure of the document using the XML markup language. Doxygen then uses it to determine what information needs to be displayed, in what order, and also partially on how to display it.

Similarly, as when changing the design of the documentation, first you need to get the default file used. To do this, use the -l command (from layout):

doxygen -l [имя_файла]

The top level of this file is as follows:


    ...
  
    ...
  
    ...
  
    ...
  
    ...
  
    ...

Details of working with this structure are described in the corresponding section of the official documentation.

We only note that after you have created your file, you need to change the LAYOUT_FILE option in the settings file , indicating the path to this file in it:

LAYOUT_FILE = <путь_к_файлу>

Structure Change Example

Again, in order to gain confidence in our capabilities, we will make a small change in this structure.

First of all, we will generate a file with a structure (as was done above), and then add a new tab to the menu. Tabs are added using the tab tag , and in this case, when adding a new tab, you must specify the user type to it .

Further, since we want to add a tab to the menu, we need to find the corresponding section (for the menu it is navindex ) and add our tab to it:

...

Pay attention to the value of the url and title parameters , the first provides a transition to habrahabr.ru when you click on this tab, and the second reflects the text on the tab.

The result will look like this:

Documentation Examples

After we figured out how to set up documentation, it was time to look at ready-made examples that you can use for your projects.

Qt4 theme

Below is a sample documentation created on the basis of a topic that copies the Qt documentation of the fourth version.

Bootstrap theme

A theme was created especially for Bootstrap fans .

Two more examples

Using the following link, you can familiarize yourself with and download two topics at once for documentation.

Conclusion

To summarize, I would like to note that it was rather difficult to find ready-made topics for documentation, but in fact the functionality that Doxygen provides for customizing the design is very extensive and makes it easy to customize the documentation to your taste, so I hope that this article will help you do Your documentation is more beautiful and more pleasant for the reader.

Thanks for attention!

Tags: