doxygenclass inconsistent rendering

[danwos]

It looks like that there are certain rendering problems of rst-code when using doxygenclass. Rendering the same rst-code by using doxygenfile or doxygengroup works perfectly.

There is a standalone sphinx-example-project for this here: https://github.com/useblocks/sphinx-scale/tree/main/demos/needs_doxygen_breathe

Error Examples

Asterisk handling

/**
 * \brief Hello world
 * \rst
 * This should be **bold**
 * \endrst
 */

Output via doxygenfile:

Output via doxygenclass: Looks like a leading asterisk got removed from rst, before it got rendered.

Specific role handling

I'm using the extension Sphinx-Needs to create some objects, which can be referenced by using the role need. It's something like the normal Sphinx role :ref:.

/**
 * \brief Hello world
 * \rst
 * .. need:: Test me
 *    :id: NEED_1
 *
 * A reference to :need:`NEED_1` 
 * \endrst
 */

However, when is use :need: inside a docstring and let it get documented by doxygenclass, I get the following error:

Exception occurred:
  File "/.../.venv/lib/python3.9/site-packages/docutils/nodes.py", line 2018, in unknown_visit
    raise NotImplementedError(
NotImplementedError: <class 'breathe.renderer.sphinxrenderer.NodeFinder'> visiting unknown node type: NeedRef

This works perfectly, when using the same docstring and document it via doxygenfile or doxygengroup.

Directives from Sphinx-Needs are working with doxygenclass. Internally Sphinx-Needs replaces a NeedRef-node with a docutils internal ref-node (like used by :ref:), so that the docutils-node-tree does not contain any Sphinx-Need specific nodes in the end. But it looks like that doxygenclass is rendering something, before this replacement gets done.

Test details

Tested with Breathe version 4.28.0 and 4.30.0. Sphinx 4.0.2 and 3.5.4

Not tested (yet):

• Support for specific roles from other extensions
• Other doxygen... directives. Only file, group and class.

[twodrops]

@danwos Thanks for the detailed issue report. Could you also please specify the Sphinx version used?

[danwos]

Tested it with Sphinx 4.0.2 and 3.5.4 (Added also to issue description)

[arwedus]

I have the same problem. Sphinx v. 4.2.0, breathe v 4.31.0