Headlines are not shown

[rweickelt]

Headers from doxygen documentation are not printed in Sphinx/Breathe.

I've tried different markup styles from within a class documentation:

/*!
 This is a documentation

<h2>Header</h2>
Text

Header
---------
Text

### Header ###
Text
*/
class Test {};

None of them worked. They are simply missing in the output. Everything else is shown normal. I guess that Breathe supports any markup syntax that Doxygen understands. So I consider this to be an error. Or am I missing something?

[michaeljones]

Hi,

Curious! I imagine that is a bug in Breathe. I don't think I've explicitly tested for them before. The interesting question is always: what does the Doxygen xml look like? I imagine it is all there but using some xml node that Breathe isn't handling at the moment.

Thanks for reporting the issue :)
Michael

[rweickelt]

Thanks to Your explanation in issue #81 I ended up with a working renderer stub

class DocHeadingTypeSubRenderer(Renderer):

    def render(self):
        return [self.node_factory.Text("This is heading")]

which actually prints the text instead of the headline.

Now I'm lost. Docutils does not a have a class for headings, but only for sections. Sections in docutils are kind of a super-node for the section content while doxygen does not care about the section structure and just embeds a heading element on equal level as any other paragraph. Can anybody confirm that?

[michaeljones]

Thanks for following that up. I'm glad the #81 explanation helped and thanks for the reminder that it is there. I meant to port that into the docs at some point.

I agree that headings have a special significance in docutils and I'm not sure how to go about creating titles without them. It might be worth investigating what sphinx autodoc does for headings placed in Python rst docstrings. Perhaps that will provide guidance or maybe we'll have to find our own way here.

I'll try to have a look at that this evening.

[rweickelt]

I've realized, that member documentation uses emphasized text instead of sections. Breathe directives do not add anything to the TOC. How about doing the same with headings? I would rather like to see a comprehensive solution (issue #38). I'll submit a pull request.

[michaeljones]

Hey,

Thanks for investigating it further and for the pull request. It looks nice and clean and I'm happy to merge it in. And sorry for taking longer than promised to look at it. I've got to stop giving brief time scales as I rarely make them work.

I am a little confused though. From my tests, if you put a RST heading in a Python docstring and use Sphinx autodoc, then it puts out a warning and basically ignores the heading in the final output. If I look at the Doxygen html for your example then Doxygen does honour the headings and puts out h2 and h3 tags as required.

So I'm not sure what you are referring to when you say 'that member documentation uses emphasized text instead of sections'? Otherwise, I'm happy to treat them as emphasized text. We could possibly add custom classes to them so that people have the option to style them like headings if desirable.

I'm sorry for the lack of progress on #38. It is desirable but I don't know where to start with it so I haven't blocked out the time. Thanks for the reminder though, as I am also guilty of forgetting about some of these issues.

Cheers,
Michael

[rweickelt]

Hi,

no need to feel guilty. I can not see any paying customer out there ;-)

I am a little confused though. From my tests, if you put a RST heading in
a Python docstring and use Sphinx autodoc, then it puts out a warning and
basically ignores the heading in the final output. If I look at the
Doxygen html for your example then Doxygen does honour the headings and
puts out h2 and h3 tags as required.

That in turn confuses me ;-) Of course Doxygen creates heading elements. But
this is not enough for docutils.

So I'm not sure what you are referring to when you say 'that member
documentation uses emphasized text instead of sections'? Otherwise, I'm
happy to treat them as emphasized text. We could possibly add custom
classes to them so that people have the option to style them like
headings if desirable.

My knowledge about Sphinx is still very limited. But as far as I am aware,
it is all about TOC trees. Every document shall have a strict tree structure
that is, a document has a title, and consists of sections. Each section has
a title and maybe subsections which again have titles and so on.

Looking at a doxygen class documentation, one could now argue, that this
should be a structured document as well. "Public functions", "Public Static
Functions", ... would be titles of sections and the detailed description of
each function would be a subsection either. But instead, everything is just
a single plain section and headings like "Public functions" etc are rendered
as emphasized text.

And because breathe does not generate structured output, we can not utilize
Sphinx to create an automatic TOC for us. That is why I was referring to #38
here.

BTW: This is a good example for a well-structured class documentation and my
personal goal: http://qt-project.org/doc/qt-5/qstring.html

The doxygen xml-output contains all necessary information for that.

[michaeljones]

Ah, that's make sense. I didn't realise you were referring to the current output. Yes, Breathe doesn't create any sections itself and everything is just styled and indented text. And you're right that that is probably key to having Sphinx create a nice TOC for us.

I am happy to investigate using sections. It is not something I've ever done from the docutils API and I wonder how it all works to be honest. The only two concerns I have are:

1. I like the indented formatting of the output and I think sections are probably always aligned to the right. From a simple test, it seems you can't put sections in indents. Testing with: https://www.tele3.cz/jbar/rest/rest.html. That said, your Qt example is a good one and looks fine without indentation in that format. Maybe it could be a user choice.
2. As far as I can tell sections have their appearance determined by their importance (h1, h2, h3) and their importance determined purely by their order. So I'm concerned that if you have two document headings (h1, then h2) and then some Breathe output, it might look different to if you only have one document heading (h1) and then some Breathe output. If that makes any sense. In the first case the Breathe output class heading would become an h3 and in the second case it would become a h2. Though I guess the docutils API might offer more control than that.

I can't really say what is and is not going to be a problem until I write some code and poke around at the results. I guess the concerns have slowed me down when it comes to embracing this idea.

I might try to ask about that second issue on the docutils list and see where we go from there.

I should probably try to look at the output of Sphinx autodoc for Python classes as well as that is kind of what I'm modelling Breathe after (though other influences are good.) I suspect they don't use sections there either but I'm not sure.

Cheers,
Michael

[michaeljones]

From the pseudo-xml here it looks like sections are purely order based, there aren't additional parameters to specify their importance.

Also, unfortunately the sentence:

Paragraphs and other body elements may occur before a section, but not after it.

Indicates that we can't have a structure that would look like:

Section

Text

Class (Sub Section)

     Class contents (Sub Section)

More text.

Class

As the More text line comes after the Class contents section heading. Might not be the biggest issue but it'll hinder the mixing of free text and breathe output.

There might be other docutils nodes that we can use to achieve similar results (inclusion in the automatically generated TOC) without sections. I'm not sure.

Cheers,
Michael

[rweickelt]

Hi Michael,

thank Your for the reply and the link to the docutils page. It explains very
well, why the html-ish/serial/loose-structured doxygen output needs further
processing before it can form a valid tree-ish Sphinx document.

What You are saying makes totally sense from the Py API point of view. I
always had this "one class per document" thing in mind. It might result from
the fact, that this is what doxygen produces by default: Interlinked class
documentation pages.

Having one class per document, no indentation is needed at all and the
document structure is very clear. But with arbitrary classes on different
levels we face exactly those problems You've mentioned above.

I would like to know, how others think about that. How are they going to use
breathe? How should a good documentation look like? This brings us again to
the topic of my failed post on the mailing list ;-)

[vermeeren]

In current versions of Breathe the headings are rendered in italic, so I guess this has been implemented in some way.

Closing for now as I think this is okay, please comment if I'm missing something.