How to split doxygen @mainpage documentation across several files

Question

I would like to include in the @mainpage section multiple .txt files (or .md files, written in markdown).

However, I get for each of these text files a separate chapter. How can this prevented?

Answer 1

I am here looking for an answer to the same problem, and since no one appears to have solved it, I have looked for a solution myself.

I have found this ...

http://www.doxygen.nl/manual/preprocessing.html

Source files that are used as input to doxygen can be parsed by doxygen's built-in C-preprocessor. By default doxygen does only partial preprocessing.

So to split a page, e.g. the main page over several files, it looks like a solution is to fully enable the C preprocesor on the markdown files, and to use

#include file1.md

#include file2.md

etc to include the various markdown files.

What we would like to do is use Doxygen 's

\include file1.md

\include file2.md

but unfortunately Doxygen has second guessed that the files we want to include are code files. In the same way that Doxygen has a \htmlinclude to save you writing two lines

\htmlonly

\endhtmlonly

specifying that the content is HTML, the \include command is really a sort of \codeinclude to save you specifying that the included content is software.

I would personally prefer to type an extra two lines specifying the nature of my included files: code, HTML, markdown, or whatever, and have a generic include command. But they say never look a gift horse in the mouth, which basically means you cannot argue with free software!

Answer 2

You could do something like this:

@mainpage
This is your live and it isn't getting any better then this! This is your life and it's ending one minute at a time!
<a href="/mnt/home/USER/vis/Doxyfile">Doxyfile</a> @n
<a href="/mnt/home/USER/vis/DoxygenLayout.xml">DoxygenLayout.xml</a><br>

Put a @n, \n, <br> after each refrence, to break lines, otherwise everything will be put in one line.

---

You can also define a group, add the other refrences to that group:
@mainpage
@ref test

First, you put the @ref tag to your mainpage. Then you define a group e.g.

@defgroup test
@{
<a href="/mnt/home/USER/vis/Doxyfile">Doxyfile</a>
@}

Now you start adding links, from other files, to that group with:

@addtogroup
<a href="/mnt/home/USER/GROUP/Doxyfile">AnotherDoxyfile</a>

However this will show only the groups name in your mainpage, not all files.

---

I assume what you want is, to put an anchor in a file:

@anchor ANCHORTEST
@{
<a href="/mnt/home/stud-dral1012/vis/Doxyfile">TESTFILE</a>
@}

And then later put that anchor in your mainpage:

@mainpage
@ref ANCHORTEST @n