Advice on changing generated layout

[clauniel]

I would like to change the way classes and functions are rendered, to something more like this: http://stlab.cc/libraries/concurrency/channel/

How would I go about doing this? It appears there are no templates for the generated output for class and function directives neither in Sphinx itself nor in Breathe. Is the html layout hardcoded into Sphinx?

Autosummary appears to have overridable templates supported by the :template: keyword, but breathe does not use autosummary afaict.

I am willing to modify Breathe to be able to take rst templates in the same form as those used by autosummary, but from reading the other issues it seems that all rendering layout is delegated to Sphinx itself and this is not the appropriate place to add such functionality.

[vermeeren]

I am not 100% sure about anything I am about to post, but I believe it is currently some odd hybrid. In the past Breathe's sphinxrenderer.py did output a lot of RST, but with the c/cpp domain existing in Sphinx nowadays a big part of data is simply forwarded to Sphinx which does the actual rendering.

So it is likely that a part of the rendering still happens in Breathe (legacy implementation) and a part of the rendering happens in Sphinx (modern implementation). The HTML theme also determines how things look, but I have no idea how much of the end result is decided in the theme. It is likely all three things need changes to have truly flexible layout options.

For Breathe specifically: it should forward everything to Sphinx and let Sphinx handle all the rendering and styling. This is sort of the plan for Breathe v5 if it will ever see the light of day.

[jakobandersen]

To elaborate a bit on what @melvinvermeeren wrote and dump a few thoughts. My understanding is that Breathe now delegates almost all handling of the actual C++ declarations to Sphinx. However, the orchestration of which declarations to render at which position is still in Breathe (which I believe is the right choice). Before this can be template the issue #354 should probably be fixed, though it is rather non-trivial. Note that the different domains in Sphinx are basically independent mini-compilers that takes care of the peculiarities of each language. Autosummary looks like a very Python-specific thing, though the idea can of course be translated. Your suggestion is somewhat related to sphinx-doc/sphinx#4981 , though here more in the spirit of automatically creating a synopsis for a variables/classes/typedefs in a scope. Issue #321 also seems quite related. However, note that the C++ domain does not attach a short-hand description to each declaration like autodoc seems to do. Is this a concept that Doxygen has? If so, then the specific style of summary you linked to is probably a feature for Breathe.

[rweickelt]

If I understand @clauniel correctly, then we are not talking about the actual HTML style, but rather about structure of pages. The documentation he linked to is an "overview" page that links to detail pages for global functions and classes.

I assume that he is looking for some kind of template mechanism to

• define the structure of "detail" pages, such as classes
• define the structure of "overview" pages which would link to detail pages

and then he only wants to specify the classes, global functions, etc that should be contained in the autogenerated documentation.

Breathe doesn't have such a concept. It follows pretty much the structure of the Doxygen XML output for all directives and transforms the XML content more or less directly into rst nodes. A structure as shown in http://stlab.cc/libraries/concurrency/channel/ would require a fundamental architectural change in Breathe. It's probably better to rewrite it from scratch or look for alternatives such as exhale.

[clauniel]

Thanks for the comments.

As @rweickelt says I was looking for a way to display those short summaries in a two column table which link to detailed pages. I found out that Matplotlib actually has this for their pyplot module and I believe their docs are generated using sphinx https://matplotlib.org/api/_as_gen/matplotlib.pyplot.html#module-matplotlib.pyplot

That style of table is provided by the autosummary "functions" template, but this is a piece of hardcoded docutils nodes.

@jakobandersen Doxygen has the \brief command which I use as a short summary. When looking at Doxygen generated class lists using the default template they are displayed in a two column table with a class reference on the left and \brief summary on the right iirc.