Multiple \class - Documentation order

[couet]

Description
When defining the same \class in two places, Doxygen concatenates the two pieces of documentation. The order in which it does it does not seem to be controllable.

Screenshots

To Reproduce
class.tar.gz

This tar balls contains three files:

1. a.h which defines a dummy class,
2. a.C with the first \class A,
3. a.pyzdoc which contains the second \class A .

As shown in the previous picture the doc coming from the file a.C is shown first, then the doc coming from the second file a.pyzdoc is shown. The order in which these two pieces of documentation appear cannot be controlled it seems. Changing the file order in the INPUT directive in Doxyfile does not seems to have any effect. This order seems kind of random because in the real documentation the order is the opposite.

Questions

1. Is the "Multiple \class definition" really supported or does it kind of work just by chance ? I did not find any clear explanation in the web about a such feature.
2. If it is supported, what is the way to control the order in which the pieces of documentation appear ?

Version
1.9.2 (6193e56)

[albert-github]

Doxygen has no idea what the difference between the \class A in the both files might be and as a convenience concatenates the output.
Regarding the order I think this is possible depending on the names (and directories of the actual files). The file names in the example are, of course, shortened and this is also the case for the class name, so it is hard to tell based on the provided information.
Do you see somewhere an unexpected order (and what are here the original file names and directories)?

Note: the Doxyfile provided contains quite a bit of noise (e.g. HTML_HEADER which is not present in the example), would be good that this normally cleaned out a bit.

[couet]

Indeed we came up with this issue because in the page I mentioned before https://root.cern/doc/master/classTFile.html
the "python frame" (which is the 2nd \class) appears before or after the main C++ doc depending of the doxygen version. In previous versions it appeared at the end (that what we want) and now it is displayed at the beginning just after the \brief (that's we see now with 1.9.2) that's why we wondered if the double \class declaration is valid ? and if it is how to make sure the order is well defined and what are the rules to define the order ?

[albert-github]

This might have to do with the sorting order of the input files that might have changed between the versions (I do vaguely remember something).
With more extensive logs it is hard to tell what a solution might be (might be that changing the order in the INPUT tag helps.

This is also why I submitted root-project/root#8742 so I could do some tests.

[couet]

@albert-github I understand the order in which the various pieces of documentation will appear is not well defined and cannot be set in a way or an other. This lead me to an other question: Is it possible to define a piece of documentation let's say a kind of \page which would be included "in place" by some kind of \ref which would include the \page text where that special \ref is, instead of putting a link to it as a normal \ref would do ? I didn't find any thing like that in the documentation.

[albert-github]

Did you have a look at the \snippet{doc} possibilities for this?

[couet]

Thanks for pointing this I will investigate .

[albert-github]

Small quick start:
a.C

/** \class A
\brief C++ version of class A.
This is the C++ help.


\snippet{doc} a.pyzdoc class_A
*/

a.pyzdoc

/*
\noop [class_A]
Python version of class A.
\noop [class_A]
*/

[couet]

I'd like to have something simpler by putting the python doc as a .md file. I made a file aaa.md in the $ROOTSYS/documentation/doxygen folder as follow:

aaa.md

# PyROOT

In the same way as for TDirectory, it is possible to inspect the content of a
TFile object from Python as if the directories and objects it contains were its
attributes. For more information, please refer to the TDirectory documentation.

the INPUT variable in DoxyFile is:

INPUT                  = ./mainpage.md \
                         ../../io/io \
                         ./aaa.md

and I include the aaa.md file as follow:

\snippet{doc} ./aaa.md

Doing that the text in the aaa.md file does not show in place of the the snippet instruction.

[albert-github]

The \snippet{doc} has as mandatory argument also the block-id that is missing here, so you probably will have gotten a warning about this and it implies that doxygen does not know what to include.

It might be that with \include{doc} could get the results wanted.
I don't think it is necessary to add the aaa.md to the INPUT tag as the \snippet / \include runs over the EXAMPLE_PATH setting, unless of course you want to have the content of aaa.md as a separate entry as well.

[couet]

I tried \include{doc} aaa.md inside a .cxx file. I defined EXAMPLE_PATH as follow:

EXAMPLE_PATH           =  /Users/couet/git/couet-root/documentation/doxygen

aaa.md is in that folder:

% ls /Users/couet/git/couet-root/documentation/doxygen/aaa*
/Users/couet/git/couet-root/documentation/doxygen/aaa.md

That does not work . The content of aaa.md does not show where I put \include{doc} aaa.md ... it is simply ignored. Nothing shows.

[albert-github]

Please show the relevant part of the project in a, small, attached 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.

[couet]

Here is a simple reproducer and the output I get. the content of aaa.md is not shown.
include.tar.gz

[albert-github]

The problem here is the content of the aaa.md:

# PyROOT

In the same way as for TDirectory, it is possible to inspect the content of a
TFile object from Python as if the directories and objects it contains were its
attributes. For more information, please refer to the TDirectory documentation.

and the place it is included:

### Before include

\include{doc} aaa.md

### After include

The usage / handling of the the inclusion of the \section commands (i.e. the "translation" of the # here) into documents is not optimal and results in ignoring the section here.

Best would be to use the HTML alternative here like:

<h1>PyRoot</h1>

(or of course <h2> or <h3> or other levels).

[doxygen]

@albert-github I understand the order in which the various pieces of documentation will appear is not well defined and cannot be set in a way or an other.

This is not completely true. The order of processing pages can be controlled by explicitly mentioning the files in the desired order via the INPUT tag. You need to specify individual files not complete directories. This is also what doxygen itself does for creating its own manual.

[albert-github]

When I would include the aaa.md in the INPUT tag there would, in this case, be a separate page with the information from this aaa.md and it is here explicitly requested that the text is included at the mentioned place.

Did I overlook something?

[couet]

Ah yes ! that's bad luck I had this markdown formatting in the aaa.md file.
Many thanks. I will now try with the real case.

[couet]

Hi @albert-github,
So the include is working nicely. If I do

\include{doc} _tfile.py.pyzdoc

(where _tfile.py.pyzdoc contains the piece of doc) it is fine.
The piece of doc (_tfile.py.pyzdoc ) is:

\htmlonly
<div class="pyrootbox">
<h2>PyROOT</h2>
In the same way as for TDirectory, it is possible to inspect the content of a
TFile object from Python as if the directories and objects it contains were its
attributes. For more information, please refer to the TDirectory documentation.
<br><br>
In addition, TFile instances can be inspected via the `Get` method, a feature
that is inherited from TDirectoryFile (please see the documentation of
TDirectoryFile for examples on how to use it).
<br><br>
In order to write objects into a TFile, the `WriteObject` Python method can
be used (more information in the documentation of TDirectoryFile).
<br><br>
Finally, PyROOT modifies the TFile constructor and the TFile::Open
method to make them behave in a more pythonic way. In particular,
they both throw an `OSError` if there was a problem accessing the
file (e.g. non-existent or corrupted file).
</div>
\endhtmlonly

But it has to be html code . I did not manage to make it work with markdown.
Is it a known limitation ?

[albert-github]

I have no problem by supplying it as markdown (and the released 1.0.2 version: 1.9.2 (caa4e3d)).

Example: example.tar.gz

[couet]

Ok thanks. I will try again. It might be because of the <div> .. I will let you know.

[couet]

in example.tar.gz you sent _tfile.py.pyzdoc is html, that works... that the one we would like in markdown.
I am investigating.

[couet]

hi @albert-github , here is an example showing the problem I encountered including files in the documentation using \include{doc). The files in the tar ball are:

• bbb.h it defines a class BBB and includes the three following files:
• aaa.md gives the correct output but it is html and not very convenient for developpers to write doc. Moreover, to make it work, I was obliged to play with the htmlonly directive.
• aaa.html is purely html . That's not convenient for developers either but in addition <div> is miss-interpreted because many intermediate lines appear.
• ccc.md that's purely markdown. That's the format we would like for the doc writers. I suppressed the <div> making the blue background because I do not know how to do it in pure markdown. But apart from that, you can see that mark-down is not interpreted correctly: The bullet list at the top is fine. It appears as we want, but the lines' skips between the paragraphs are ignored and finally every thing after ## is ignored. So markdown is interpreted "partially" only.

reproducer.tar.gz

It would be nice that \include could include properly markdown.

[albert-github]

Problem I have is that the example is not complete so I have to comment out / change some settings in the Doxyfile.

PROJECT_NUMBER         = $(DOXYGEN_ROOT_VERSION)
OUTPUT_DIRECTORY       = $(DOXYGEN_OUTPUT_DIRECTORY)
STRIP_FROM_PATH        = $(DOXYGEN_STRIP_PATH)
STRIP_FROM_INC_PATH    = $(DOXYGEN_INCLUDE_PATH)
EXAMPLE_PATH           = $(DOXYGEN_EXAMPLE_PATH)
IMAGE_PATH             = $(DOXYGEN_OUTPUT_DIRECTORY)/html
GENERATE_TAGFILE       = $(DOXYGEN_OUTPUT_DIRECTORY)/html/ROOT.tag

and

PROJECT_LOGO           = ./rootlogo.gif
LAYOUT_FILE            = DoxygenLayout.xml
INPUT_FILTER           = ./filter
HTML_HEADER            = htmlheader.html
HTML_FOOTER            = htmlfooter.html
HTML_EXTRA_STYLESHEET  = ROOT.css
HTML_EXTRA_FILES       = ./rootlogo_s.gif \
                         ./notebook.gif
MATHJAX_RELPATH        = ./mathjax

• Looking at the result from the include of the aaa.html I see:

  <p ><div class="pyrootbox"> <h2>PyROOT </h2> 
  </div><div class="pyrootbox">
  

  i.e. the <div> is repeated and probably due to the setting in ROOT.css we now see the extra lines here.
  This also the reason why you had tho play around with the \htmlonly in aaa.md.
  Here there is probably some room for improvement.
• regarding the ccc.md and the translation from ## to \subsection and the fact that this and the rest is ignored leaves also some room for improvement though this will e a very hard task due to the moment of parsing of the \inculde command versus the \subsection command.

[couet]

Ok thanks. So for the time being there is not much I can try to improve the inclusion of full markdown. Note also that ## is not the only problem. In Markdown a blank line must be treated as a <br> in HTML. Right now the blank lines are ignored and all the text is treated as a single paragraph. I have not tested other markdown features.

[couet]

Note that if I convert ccc.md to ccc.html using pandoc then the problem with ## disappear when I include ccc.html

[albert-github]

Most likely pandoc converts ## to a <h2> or another HTML tag.

[couet]

yes <h2>

[couet]

Finally the solution adopted was to list the files containing the python Frame at the end of the INPUT list. To make it automatic the INPUT list is generated automatically via a script. The PR is root-project/root#8971 .
Thanks for you help.