Sphinx directives/primers not evaluated

[kdschlosser]

Here is an example function declaration

/**
 * Clear one or more flags
 * @param obj   pointer to an object
 * @param f     OR-ed values from :cpp:type:`lv_obj_flag_t` to set.
 */
void lv_obj_clear_flag(lv_obj_t * obj, lv_obj_flag_t f);

and this is what is output when the documentation is built.

the directives/primers are not evaluated and do not become links to the documentation for that item.

[vermeeren]

@kdschlosser Could you check

• https://breathe.readthedocs.io/en/latest/markups.html
• https://breathe.readthedocs.io/en/latest/embeddedrst.html

Relevant source files in Breathe's repo might also be of use.

[kdschlosser]

That is a lot of additional work that has to be done in order to be able to use directives. Doxygen doesn't have any issue with the sphinx directives being there and they don't get mangled in any way, Why can't the text that is collected from the doxygen xml output be fed back into Sphinx to be parsed as if it was a Python docstring or maybe like it is text from a reST file?

[vermeeren]

@kdschlosser Yeah, I think it's a good idea to add a global Breathe configuration option to, by default, parse everything as-if it was embedded in embed:rst or one of its many variants (should be configurable too probably). Looking at breathe/renderer/sphinxrenderer.py search on embed:rst I don't think it'd be too complex.

The reason it's not the default is because parsing by default could easily result in a lot of hassle, warnings, errors etc with RST syntax leading to unexpected and undesired results from people migrating from plain Doxygen.

Patches very welcome!

Edit: Doxygen commands inside embed:rst possibly will not be handled as Breathe will parse everything as RST. For example https://breathe.readthedocs.io/en/latest/markups.html#aliases the \verbatim here may change output if completely inside embed:rst parsing mode.

[kdschlosser]

the thing is a huge ? on how sphinx would react to doxygen syntax. But then again if breathe is coded to read the XML data then all of the doxygen related directives have been changed into XML tags which would make it a little bit easier to deal with, Those tags can be changed into reST syntax or sphinx directives.

In my specific use case there is nothing really special other than code with single back ticks and those are what I wanted to convert to sphinx directives anyhow. There are a lot of them and having to add all that additional information to each one of them would not make the C source very readable.

[kdschlosser]

I don't know enough about sphinx specifically the code to be able to implement something like this. Sphinx has quite a bit of voodoo magic code in it and trying to trace a data path is not the easiest thing.