How to make an introduction page with Doxygen


Doxygen Problem Overview

I made documentation for my SDK, using Doxygen. It contains the list of files, namespaces, classes, types etc. - everything that I placed as Doxygen comments in the code. Now I want to write some general information about SDK (kind of introduction), which is not related directly to any code element. I want to place this introduction on the documentation start page. How can I do this?

Doxygen Solutions

Solution 1 - Doxygen

Have a look at the mainpage command.

Also, have a look this answer to another thread: It states that there are three extensions which doxygen classes as additional documentation files: .dox, .txt and .doc. Files with these extensions do not appear in the file index but can be used to include additional information into your final documentation - very useful for documentation that is necessary but that is not really appropriate to include with your source code (for example, an FAQ)

So I would recommend having a mainpage.dox (or similarly named) file in your project directory to introduce you SDK. Note that inside this file you need to put one or more C/C++ style comment blocks.

Solution 2 - Doxygen

As of v1.8.8 there is also the option USE_MDFILE_AS_MAINPAGE. So make sure to add your index file, e.g., to INPUT and set it as this option's value:


Solution 3 - Doxygen

Note that with Doxygen release 1.8.0 you can also add Markdown formated pages. For this to work you need to create pages with a .md or .markdown extension, and add the following to the config file:

FILE_PATTERNS += *.md *.markdown

See for details.

Solution 4 - Doxygen

Following syntax may help for adding a main page and related subpages for doxygen:

/*! \mainpage Drawing Shapes
 * This project helps user to draw shapes.
 * Currently two types of shapes can be drawn:
 * - \subpage drawingRectanglePage "How to draw rectangle?"
 * - \subpage drawingCirclePage "How to draw circle?"

/*! \page drawingRectanglePage How to draw rectangle?
 * Lorem ipsum dolor sit amet

/*! \page drawingCirclePage How to draw circle?
 * This page is about how to draw a circle.
 * Following sections describe circle:
 * - \ref groupCircleDefinition "Definition of Circle"
 * - \ref groupCircleClass "Circle Class"

Creating groups as following also help for designing pages:

/** \defgroup groupCircleDefinition Circle Definition
 * A circle is a simple shape in Euclidean geometry.
 * It is the set of all points in a plane that are at a given distance from a given point, the centre;
 * equivalently it is the curve traced out by a point that moves so that its distance from a given point is constant.
 * The distance between any of the points and the centre is called the radius.

An example can be found here

Solution 5 - Doxygen

Add any file in the documentation which will include your content, for example toc.h:

@ mainpage Manual SDK
@ section pageTOC Content
  -# @ref Description
  -# @ref License
  -# @ref Item

And in your Doxyfile:

INPUT = toc.h \

Example (in Russian):

Solution 6 - Doxygen

I tried all the above with v 1.8.13 to no avail. What worked for me (on macOS) was to use the doxywizard->Expert tag to fill the USE_MD_FILE_AS_MAINPAGE setting.

It made the following changes to my Doxyfile:

INPUT                  = ../ \
                         ../sdk/include \

Note the line termination for INPUT, I had just been using space as a separator as specified in the documentation. AFAICT this is the only change between the not-working and working version of the Doxyfile.


All content for this solution is sourced from the original question on Stackoverflow.

The content on this page is licensed under the Attribution-ShareAlike 4.0 International (CC BY-SA 4.0) license.

Content TypeOriginal AuthorOriginal Content on Stackoverflow
QuestionAlex FView Question on Stackoverflow
Solution 1 - DoxygenChrisView Answer on Stackoverflow
Solution 2 - DoxygenPascalView Answer on Stackoverflow
Solution 3 - DoxygendoxygenView Answer on Stackoverflow
Solution 4 - DoxygenBirol CapaView Answer on Stackoverflow
Solution 5 - DoxygenDenisView Answer on Stackoverflow
Solution 6 - DoxygenVorpalSwordView Answer on Stackoverflow