Doxygen: Customizing the Examples Page

Question

While documenting a project with Doxygen, I encountered the following problem.

I have a set of example programs (demo_1.c, demo_2.c,...) which reside inside the EXAMPLE_PATH set in the Doxyfile. I created a file examples.c with the following content to include the examples:

/**
 * \example demo_1.c 
 * \example demo_2.c 
 * ...
 */

After running Doxygen, an Examples page is created within the navigation as I want it but the Examples section always looks like:

Examples 
--------
Here is a list of all examples:
 * demo_1.c
 * demo_2.c 

How can I change this page? I especially want to replace the text "Here is a list of all examples:" with a larger introduction.

I already generated the doxygen layout file and the header/footer files but this does not give me any useful information.

Answer 1

The solution is to create a DoxygenLayout.xml file and customize it with the information you want to appear on the examples page.

Doxygen will produce a template XML file, in the current directory, from the configuration it is using currently via the following command line:

$ doxygen -l

Point Doxygen to this file by editing the Doxyfile configuration file or using the Doxywizard GUI (Expert tab -> Build -> LAYOUT_FILE) to change the LAYOUT_FILE path to your new DoxygenLayout.xml file.

I recommend doing this step explicitly instead of relying on the default behavior to pickup the DoxygenLayout.xml when it exists in the folder Doxygen is run from.

You will need to edit the <tab type="examples"> XML tag and change the existing title attribute and add an intro attribute to suit your needs. The title attribute changes both the name of the header on the page and the TAB name across the top of the HTML browser so something shorter is better.

For example:

   <tab type="examples" visible="yes" title="ALI Library Examples" intro="Welcome to the fantastic set of examples I have prepared for your enjoyment."/>  

Produces:

ALI Library Examples

Welcome to the fantastic set of examples I have prepared for your enjoyment.

• csv-simple.tcl

Note that I could not find any information about the intro attribute in the formal Doxygen documentation. I noticed it while reading the article Adding new user Tab in the Doxygen Layout.