Doxygen: how to include a markdown page to document a group

Question

I have a rather complex project and I want to document it using doxygen.

I have no problem documenting the code and I also managed to have a nice front-page using a custom README.md file coupled with "USE_MDFILE_AS_MAINPAGE = README.md" directive in Doxyfile.

I defined several groups (@defgroup) which show up as "Modules" in my documentation.

I would like to add a "main page" to each of the group giving general information, beside the customary function/variable/type documentation.

I tried adding custom MODULENAME.md files coupled with matching @includedoc MODULENAME.md entries in group definition, it seem to work (I see several lines like: "Generating docs for page md_mcu_noitr_coro_README..."), but I cannot find if and where the page is linked (I expected to see it in the "Detailed Description" for the module, as it happens if I put some documentation inline where I put the "@includedoc" directive.

a snippet of one of my modules is:

/**
 * @file coro.h
 * @brief definition of coroutine implementing functions.
 *
 * @date: Feb 8, 2018
 * @author: myself
 *
 * @defgroup coro "Coroutine implementation in plain 'C'."
 *
 * @includedoc mcu_noitr/coro/README.md
 * @{
 *
 */

What am I doing wrong?

Note: it is also a bit surprising I need to put the whole path from where my Doxyfile is, otherwise doxygen won't find it even if it's right beside the file containing the @includedoc command.

user_10922749 · Answer

I also came across the problem that included files with Markdown formatted text via \includedoc or \include{doc} does not result in correctly interpreted Markdown. Note that I included Markdown files from other Markdown files. My work-around was to use the C pre-processor (cpp) - which is widely available - on Markdown files and use it's #include directive. You could of course use a true general text processor such as M4 as suggested in the cpp man page. Set FILTER_PATTERNS in Doxyfile as:

FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"

You'll need the -P option to avoid it outputting line markers, which confuses Doxygen. -traditional-cpp was needed to avoid cpp eating white space that is important for the correct interpretation of Markdown. Don't use single quotes as this results in an error when Doxygen calls cpp via sh.

Then in my Markdown main page:

Main Page {#mainpage}
==========

Blah blah blah.

#include "other.md"

Using FILTER_PATTERNS instead of INPUT_FILTER avoids the problem about not being allowed to add or remove lines.

I have my markdown files in the same directory, I would guess that if they are located in different places you could tell cpp about it via -I, which would address your expectations about include paths on the issue you filed.

user_1657886 · Answer

At the moment doxygen does not consider the fact that commands like \includedoc can contain markdown code. At the moment the only possibility would be to write a filter, see configuration parateter INPUT_FILTER in the doxygen configuration file, (not tested!) to replace the \includedoc` with the code of that file.

Doxygen: how to include a markdown page to document a group

2 Answers