Use previous Breathe format for field lists, notes, and warnings

[Grace-Li-cam]

Hi there,

Breathe v4.29.0 supports "Use native docutils for field lists, notes, and warnings". However, I prefer the previous version of the display. We deliver documents using this format to users already and do not want to change. It that possible to add a configuration to support both native docutils for field lists, notes, and warnings and the previous format? Thanks.

Grace

[jakobandersen]

I think it would be difficult to reinstate the exact old behaviour, but if you generate HTML output I'm somewhat sure you can get the very close to the old layout purely through CSS.

[vermeeren]

@Grace-Li-cam I agree with @jakobandersen here, the eventual rendering is mainly the responsibility of the theme used (and its settings/CSS) and I believe there is no technical limitation on Breathe's end preventing a theme rendering in old-style layout.

I'll close this for now based on the above assumption, if you find Breathe/Sphinx is lacking proper id/class tagging for elements or other problems for theme implementation do create a new issue.

Thanks

[jakobandersen]

I tried fiddling a bit with the CSS idea.

Example RST:

.. cpp:function:: void f()

	:param int a: adesc
	:param int b: bdesc
	:tparam T: tdesc
	:tparam U: udesc
	:returns: something
	:returns arg: somethingElse

With the default theme ("alabaster" (though really the CSS to be overwritten is in the "basic" theme)) this renders as

Now, add the following CSS:

dl.field-list {
	display: block;
}

dl.field-list > dt {
	font-size: 1.2rem;
	padding-top: 0.2em;
	padding-bottom: 0.2em;
}

dl.field-list > dd {
	padding-left: 2em;
}

dl.field-list > dt:after {
    content: "";
}

This can be done through a combination of https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path and https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_css_files.
Then I get

The CSS wizards out there can probably make this prettier, but as proof-of-concept I think this is a rather good approximation of the old style. And this applies to native Sphinx stuff as well, not just stuff that Breathe has generated.