Fix code block highlighting by 2bndy5 · Pull Request #760 · breathe-doc/breathe (original) (raw)

well there isn't much in the doxygen test suite with code snippets, but I found this:
image (compared to the live docs currently hosted on RTD)

BTW, I'm not a big fan of the theme used here for the docs because, among various other reasons, the code blocks' differently colored parts are hard to visually distinguish. The RTD theme has this problems as well. Browser extensions like "dark reader" can only help so much.

Discovered a new issue

There's also an instance where pygments fails to guess what syntax is used. This instance exists under the doxygen test suite for the python docstrings (ironic - I know) named pyexample.
image link to live hosted docs on RTD for comparison
The fact that these docstrings are interpreted as literal code from XML seems to be a problem with doxygen. Locally with v1.9.3, doxygen's XML produces no literal code blocks from the pyexample test. I know the CI uses v1.8.17, but RTD might be using something older (possibly the same version if they updated their docker image to use Ubuntu 20.04).

I don't see anything else in the docs that is making use of these changes. All the snippets in the TinyXml lib's example docs seems to remain unaffected. Meaning, pygments is still trying to automatically guess the code blocks' syntax just as before.

The real feature of this PR makes use of code blocks that look like so (to doxygen parser):

@code{.cmake} set(user_list A B C) for(element in ${user_list}) message(STATUS "Element is ${element}") endfor() @endcode

where pygment is passed whatever is in the curly brackets when doxygen correctly outputs that as part of the XML.