Hi @ihrivnac, thank you very much for your PR! I have two questions:

• Can you please generate the webpages and have them published to your web space, so that we can see them (and discuss tomorrow at WP3?)
• Does this PR solve the problem of Doxygen tags being mixed up with Markdown?

Thanks for your efforts!

Hi @dberzano ,

The new generated documentation is available at:
http://ivana.home.cern.ch/ivana/o2_html3/index.html

The PR does not solve the problem of Doxygen tags being mixed up with Markdown; the problem is that Markdown processing precedes Doxygen and so if we comment out the Doxygen keywords for Markdown, they are not seen by Doxygen.

A reasonable compromise is to have the top README.md page free of Doxygen keywords, but use them in the bottom pages. Otherwise we would need to think about implementing some filtering procedure which would be triggered from CMake when generating documentation. But I don't think that it is worth the effort.

Not necessarily, but with using these we make get clearer documentation when referring to this page from other place: eg. see more in Module XXX, instead of see more in XXX.
And the second reason for this that it makes non-structured bottom pages (if someones add a new page without the Doxygen keywords) better apparent in the list on the left.

Yes for the first reason; but not for the second one. Actually in the re-generated documentation there is a newly added page "O2 Framework Foundation" which pollutes the global "namespace". Once the "Module " is removed this would get hidden in the list of the top directories.
But if you are really bothered with this naming, I have no problem with removing it.

Thanks Ivana for the updated doc.

The markdown thingy is still bothering me. There is one more problem : the code samples. They are not colorized in doxygen (and the language hint of the markdown does appear as well in the doxygen generated page).

In fact, the issue is a bit more general for me : I much prefer the rendering of GitHub markdown than the Doxygen one : I find it easier to read. So, am I challenging the need for Doxygen altogether ? Well, maybe ...

This is because you are using Markdown syntax for code highlighting; when replacing
-```c++
+\code{.cpp}
you get the code highlighted in Doxygen documentation:

To get both, we would need again to implement some filtering to get rid off the other tool keywords in the representation.

I fully agree with @ktf. Code must render properly here on GitHub using standard Markdown.

• Note it's possible to preprocess code in Doxygen using an input filter: we can have it working properly here on GH, and stripped out of all the things Doxygen does not like thanks to the filter
• AFAIK Doxygen can already correctly interpret the Markdown syntax for code blocks, and you can mix Doxygen and Markdown if you want. What am I missing here?

Yes, Doxygen can render ok Markdown but Markdown does not understand Doxygen keywords which we need to create a structure of documentation pages. So we need to make these keywords invisible for Markdown, but then filter-out the Markdown comments to get the keywords seen by Doxygen,

There is now updated the README in Utilities, see:
https://github.com/ihrivnac/AliceO2/tree/doxygen-update/Utilities

and its source:
https://raw.githubusercontent.com/ihrivnac/AliceO2/doxygen-update/Utilities/README.md

The filtering command, which should be applied for processing with doxygen should be:

cat source/README.md | sed '/<!-- For Doxygen/d' | sed '/---- end Doxygen -->/d' > destination/README..md

If you find this way ok, I will take a look how to introduce the command above in the Doxygen filter. Or if you know how to do it, let me know.

I added the filtering in the Doxygen configuration file; this uses a new script filter_for_doxygen.sh added in doc/scripts. If this approach is ok for you, I will update the other README files as done for Utilities, plus the documentation page.

Hi @ktf @dberzano,
Could you, please, comment on the proposal above?
Thanks,
.

Discussion seems to have stalled here. We should address this in the next WP3 meeting (@dberzano).

@ihrivnac as discussed at the last WP3: this one is good to be merged, except for one very minor thing. We now have:

<!-- For Doxygen
\page refUtilities Module 'Utilities'
---- end Doxygen -->

We believe we can have it much shorter:

<!-- doxy
\page refUtilities Module 'Utilities'
/doxy -->

This means that the script can simply do:

sed -e 's|<!-- doxy||; s|/doxy -->||' "$1"

With this one modification we're good to go. I took care of it so I am merging it.

Thanks @ihrivnac for making it happen!