Differences rendering between versions

[Andrei1Byte]

Hello,

I'm generating documentation using Breathe in combination with Sphinx and Doxygen for C, and until now using Sphinx = 3.5.4 Breathe = 4.27.0 and sphinx_rtd_theme = 0.5.2 the documentation was rendered like this

The Parameters and Returns were separate chapters, and each parameter or return value was represented on a row. Also the name of the parameter and the return values were with a different color than the explanation.

But now I order to fix #655 I have to update Sphinx to 4.0.1, but I also have to update Breathe to 4.30.0 because of this:

But now the page is rendered like this:

The Parameters and Returns don't have separate chapters anymore, and no color is used for the name of the parameters and return values.

Was this render changed in Breathe > 4.27.0 ?

I prefer the older render because the information is much more obvious, and easier to follow :D

[vermeeren]

@Andrei1Byte I think your issue is effectively the same #693, can you check?

[Andrei1Byte]

@vermeeren Theoretically I think it seems to be the same issue, as what I observed is that between the versions there is a difference in the render.

In 4.27.0 it was like this:

For example Parameters were a subchapter with a gray background and values were listed as a list and marked in red.

But now with 4.30.0 is like this:

No subchapter with gray background, and the values are not marked with red. And also the return values are inserted separately, instead of only Returns: STATUS_OK and STATUS_ERROR as a list, as for the parameters.

Here you can find the documentation generated with the different versions:

Sphinx = 3.5.4 Breathe = 4.27.0 and sphinx_rtd_theme = 0.5.2
old.zip

Sphinx = 4.0.1, Breathe = 4.30.0 and sphinx_rtd_theme = 0.5.2
new.zip

And this is the project
GenerateDocumentationForCFiles.zip

So was this part with subchapter with gray background and values marked with red a intended change, or ?

[jakobandersen]

This is a side-effect of switching to translating paramters, exceptions, returns, etc. to using the field lists in Docutils/Sphinx. I think we can break it into 3 semi-orthogonal issues:

• The multiple returns due to multiple \revals. This is entirely on the Breathe side and should be better/fixed with Collapse multiple retvals into a single bullet list #697.
• Having headers. This is also entirely on the Breathe side. I suggest adding a directive option for specifying whether to split the fields into sections with headers and not. And then a config variable to set a default.
  Perhaps we should even take a step back and figure out a way to customize the elements in descriptions in general. There is already the config variable breathe_order_parameters_first to partially customize some elements. See also https://github.com/michaeljones/breathe/blob/8269283508d0360d544415a0faeb66c320c09f88/breathe/renderer/sphinxrenderer.py#L869
• Markup. For most fields this is happening in Sphinx and there is currently a limitation in how each domain can customize it. Some of it should be better if Call roles in typed fields sphinx-doc/sphinx#9155 gets merged, but I think that will only improve markup of exceptions and parameter types, not the parameter names and parameter direction.
  For \retvals the markup is entirely in Breathe. We could use the c:expr/cpp:expr role for C/C++ constructs, assuming the \retval argument is always either an expression or a type. Is that assumption true?

[Andrei1Byte]

@jakobandersen Thanks a lot for the detailed explanation, so it is because now Breathe is using Docutils.

I know that there are different coding flavors and no one can implement something to please everyone, for me personally the old render has a bigger visual impact and you can easily follow the information, as it is structured with headers and marked with different colors.

As I don't have a lot of experience with Breathe /Sphinx and so one, maybe can you or @vermeeren create an issue related to adding a new directive, or even customize the elements? As you have more info in the topic and I'm peaty sure you guys can detail the issue in a better way than me.

By the way, one thing that I just saw that if I have in my code " @param [in] a This is an int parameter " using 4.30.0 it will end up like a - [in] This is an int parameter , so first is the parameter name and then [in], in 4.27.0 it was [in] a : This is an int parameter, first [in] and after that the parameter name. This is again a side-effect of how Docutils is handling the fields?

[jakobandersen]

A bit more background: Docutils provides the underlying infrastructure for representing documents and manipulating them. Sphinx then layers on top of that and provides, for example, infrastructure for documenting APIs in different languages ("domains"). Breathe is then an extension on top of that, that converts Doxygen XML into document fragments, using the Sphinx domains and Docutils nodes.

The change of where the parameter direction is rendered is due to how fields are handled by Sphinx and the domains. A parameter field in the C domain (and most other domains). can have the following form: :param Type Name: Description, or :param Name: Description with an additional field :type Name: Type.
Importantly, the Type is being reinterpreted by the C domain to render it nicely, and make identifiers into links to their declaration, if possible. Unfortunately there is no direct support for the direction, so effectively Breathe constructs something equivalent to :param Type Name: [Direction] Desc.
Essentially the same issue is in Sphinx reported in sphinx-doc/sphinx#3346, but to really fix this properly the central field list handling in Sphinx needs to be generalized.

[Andrei1Byte]

@jakobandersen Thanks a lot for the explanation.

Can some of you guys handle the issue for customization of the elements ?