How to make an introduction page with Doxygen

Question

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?

https://stackoverflow.com/a/13442157/4361073 – parasrish Oct 30 '17 at 08:20 — parasrish, Oct 30 '17 at 08:20

score 114 · Accepted Answer · edited Dec 22 '18 at 12:05

Have a look at the mainpage command.

Also, have a look this answer to another thread: How to include custom files in Doxygen. 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.

At least markdown files (`.md` and `.markdown`) are considered as additional documentation files as well. I prefer them over `.dox` because they don't need surrounding code comments and can be nicely edited with a markdown editor - without drawbacks. — Pascal, Dec 13 '17 at 08:44

score 87 · Answer 2 · answered Oct 07 '14 at 20:20

87

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

INPUT += README.md
USE_MDFILE_AS_MAINPAGE = README.md

answered Oct 07 '14 at 20:20

Pascal

16,846
4
60
69

6

In addition to this, if you're going to use README.md as the main page, make sure it comes first in the INPUT list. When there are multiple mainpage candidates, the first encountered while parsing is selected, or so it seems. – Lester Peabody Sep 03 '15 at 19:09
3

By the way, in doxygen gui you only have to include your .md file under expert > input > input. – Adrian Lopez Mar 06 '16 at 03:59
1

`USE_MDFILE_AS_MAINPAGE` did not work for me. According to the documentation, you have to include `{#mainpage}` after the title of the markdown document. This did work. – samvv May 20 '16 at 11:41
3

@samvv I did not add any extra to the markdown document. I just used the `INPUT = README.md` then `INPUT += src` (to follow @Lester's suggestion) and the `USE_MDFILE_AS_MAINPAGE = README.md` and it worked like a charm. Version: `$ doxygen --version` returns `1.8.11` to me. – Xavi Montero Jul 10 '16 at 11:17
Hmm ... strange. Will try it out if I have the time and update it here. – samvv Jul 10 '16 at 13:28
1

In Doxygen 1.8.2, the only thing that did work is adding `\mainpage` inside (can do that in a comment (see [this link](http://stackoverflow.com/questions/4823468/comments-in-markdown) about comments in MarkDown). This still created Related Pages area, with a placeholder (empty). That's annoying, but at least I got the main page – Evgen Dec 12 '16 at 07:46
To make @LesterPeabody's comment more precise - the README.md file needs to be the _very first_ entry in the INPUT list, not just the first "mainpage candidate" in the list. At least for me with doxygen 1.8.13. I didn't have to add anything to the markdown to get it to work. – davidA Aug 05 '17 at 00:06
it works when added to the end of Doxyfile, however, all generated contents including nav bar to be shown manually – Dee Dec 30 '20 at 08:01
The point from [VorpalSword's](https://stackoverflow.com/a/47519611) comment to terminate the line with a backslash worked for me. v1.9.5 – Destry Dec 22 '22 at 23:19

score 59 · Answer 3 · edited Jun 15 '19 at 08:36

59

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:

INPUT += your_page.md
FILE_PATTERNS += *.md *.markdown

See http://www.doxygen.nl/manual/markdown.html#md_page_header for details.

edited Jun 15 '19 at 08:36

Kevin

16,549
8
60
74

answered Mar 01 '12 at 19:29

doxygen

14,341
2
43
37

7

Actually the current 1.8.0 version support markdown BUT doesn't treat them as documentation. So you'll end up with markdown classes listed in Files and Directories section. Solution is to add `dox=md` as an `EXTENSION_MAPPING` and rename your markdown extensions to `.dox`.So the config will look like: `INPUT += your_page.dox EXTENSION_MAPPING += dox=md` – antitoxic Mar 14 '12 at 09:37
6

Good point. I'll correct this such that .md and .markdown are treated similar to .dox. – doxygen Mar 17 '12 at 23:25
4

Unfortunately, this ends up under Related Pages, not as the main page – Evgen Dec 12 '16 at 02:09

Birol Capa · Answer 4 · 2017-02-13T14:28:12.787

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

@FelixSFD thank you for your feedback. I updated my answer according to your answer. — Birol Capa, Feb 13 '17 at 14:31
Correct, adding it to the input does not do it, it has to be formatted as above (a comment). — Scott Franco, May 13 '22 at 06:12

score 5 · Answer 5 · edited Nov 22 '17 at 00:43

5

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

@ mainpage Manual SDK
<hr/>
@ section pageTOC Content
  -# @ref Description
  -# @ref License
  -# @ref Item
...

And in your Doxyfile:

INPUT = toc.h \

Example (in Russian):

edited Nov 22 '17 at 00:43

Lucas Siqueira

765
7
19

answered Apr 12 '13 at 13:01

Denis

69
1
1

1

The scale-tech links are dead now. – Ben Fulton Nov 15 '17 at 21:12

score 4 · Answer 6 · answered Nov 27 '17 at 20:52

4

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:

USE_MDFILE_AS_MAINPAGE = ../README.md
...
INPUT                  = ../README.md \
                         ../sdk/include \
                         ../sdk/src

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.

answered Nov 27 '17 at 20:52

VorpalSword

1,223
2
10
25

1

clarification - doxywizard is the GUI front end that installs on macOS. – VorpalSword Nov 27 '17 at 20:53
I had to add \mainpage to get README.md to be recognized as the mainpage – JBaczuk Feb 02 '18 at 01:15

How to make an introduction page with Doxygen

6 Answers6

Linked