Include markdown file in mainpage.dox

[fjp]

Hi, I think this issue is related to #6478. I am trying to include a README.md markdown file into my doxygen mainpage.dox with the following result:

I started using \include{doc} but this doesn't include the text as shown in the image above.
Using the obsolete \includedoc the content is included but the markdown heading is not formatted correctly.

Using markdown inside mainpage.dox is working great though.

Is it possible to include such a formatted markdown or would this require an enhancement?

Here is the mainpage.dox:

/**
\mainpage
\htmlinclude manifest.html

\includedoc README.md

\include{doc} README.md

\include labelid

## Test heading

test text 

The content of the README.md is:

## Hardware Interfaces               {#labelid}

Test text inside README.

I am using doxygen verison 1.8.13

[albert-github]

With the above snippets it looks to me that they are not 100% complete:

• missing */ in mainpage.dox
• settings in your doxygen configuration file
• missing file manifest.html
• missing file labelid

It looks like I can reproduce the problems you see and the number of warnings look like to be a bit less and more consistent with version 1.8.17 (and with the current master), but to get a consistent test possibility:

• Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.

[albert-github]

Note also that the syntax \include{doc} was not yet supported with 1.8.13 (introduced with 1.8.15)

[fjp]

Hi @albert-github thanks for the infos and sorry for the incomplete example I just copied part of the mainpage.dox file. manifest.html is part of ROS which has a python command line tool rosdoc_lite that is a wrapper for doxygen. They use a Doxyfile template.

However, I was able to replicate the issue with a minimal working example markdown_doxytest.zip. In this example I've also removed {#labelid}. I thought that this label could be used as reference for \include instead of using the file name (README.md in this case) as described in Header Id Attributes. Please let me know if this is not the case or if I use it the wrong way. Thank you.

[albert-github]

We have here the main issue about the fact that the \include{doc} is not markdown processed, like it is stated in https://stackoverflow.com/questions/52120027/doxygen-how-to-include-a-markdown-page-to-document-a-group/52126583#52126583 as well and looks like it has not been fixed at the moment (or is not really feasible). The documentation is not clear about the fact that markdown with \include{doc} doesn't work.

Regarding the reference to the main mapge. From the \mainpage documentation:

You can refer to the main page using: \ref index.

so when you use \ref index you get a link to the mainpage, (see also the documentation of \ref for the documentation about \ref).

[albert-github]

I did a quick test where I put the line:

     inc_text = processMarkdownForCommentBlock(inc_text,fileName,inc_line);

just before

     internalValidatingParseDoc(this,m_children,inc_text);

in the routine DocPara::handleInclude of docparser.cpp, this does work a bit, but e.g. a line like:

## Hardware Interfaces {#label}

results in the fact that the line (and the rest of the file after this line) isn't shown, but without any message. With e.g. the \page command we get a message like:

warning: Found unknown command '\page' 

(but this is probably a command that is meant as not to be working for \include{doc}

@doxygen

• do you have some ideas
  or
• should an extra option for \include e.g. doc_md be added
  or
• do you think the inclusion of processing with markdown should not be done at all

[albert-github]

Looks like similar issue reported also as: https://stackoverflow.com/questions/64628591/providing-documentation-within-an-external-file-for-c-sharp-within-doxygen

[SMTStuck]

Having similar issues as well - is this going to be addressed at all in any way? Even if it is nothing will be done about it, or yes it will be fixed then at least I know to put effort into another piece of software or stick with Doxygen.

[albert-github]

As written before it looks like \include{doc} is not markdown processed.

@SMTStuck you wrote

Having similar issues as well

this is a bit vague so please:

• Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem you have? Please don't add external links as they might not be persistent.
• Please also specify the full doxygen version used (doxygen -v).

[SMTStuck]

Hello Albert,

Thanks for replying. To be honest, any further sample would be redundant - the two links to StackOverflow you have posted cover my problem in full.

As written before it looks like \include{doc} is not markdown processed.

I do not know enough of the Doxygen structure and source code. Would this require a large amount of work to overcome?

Thanks.

[albert-github]

Most likely there must be a some reentry for the new content. I looked at it in April but as you can see I didn't succeed properly at that moment. It is definitely worth to look again at the problem, it will probably take some effort to look into it again (and there probably isn't an easy solution).

[SMTStuck]

Okay, thank you anyway. Hopefully @doxygen may consider this an important issue as it would make generating documentation for complex source code much simpler.