Breathe produces an invalid document tree

[brechtm]

From brechtm/rinohtype#312 (comment)

Breathe produces a document tree with a literal_block as a child of a paragraph node. Paragraphs should only contain inline elements and literal_block is a body element.

This is what Breathe outputs currently:

<desc_content>
    <paragraph>
        some description 
    <paragraph>
        <emphasis>
            command syntax
    <paragraph>
        <literal_block force="False" language="default" linenos="False" xml:space="preserve">
             cmd-name
    <paragraph>
        <emphasis>
            output
    <paragraph>
        <literal_block force="False" language="default" linenos="False" xml:space="preserve">
             command output description

This should be:

<desc_content>
    <paragraph>
        some description 
    <paragraph>
        <emphasis>
            command syntax
    <literal_block force="False" language="default" linenos="False" xml:space="preserve">
         cmd-name
    <paragraph>
        <emphasis>
            output
    <literal_block force="False" language="default" linenos="False" xml:space="preserve">
         command output description

Unfortunately, neither docutils not Sphinx check that the document tree produced by extensions respect the distinction between body and inline elements. I have proposed this on the docutils development mailing list, and while they agree that this is a good idea, this functionality will likely not be available soon.

[2bndy5]

I think this stems from how Doxygen XML output is formed: Almost everything (in a member's description) goes into a paragraph node (in XML).

Can you post the XML output for this scenario? Or better yet a simple example project (uploaded as a zip file) that reproduces this scenario?

[jakobandersen]

The XML is basically translated one-to-one into doctree constructs so indeed when Doxygen puts it in a paragraph then Breathe does so as well. Though we have some cleanup steps, most notably for info-fields, but with #833 I have added a check for this case. It works locally for me with the following source code:

/**
 * @brief some description
 * 
 * # command syntax
 * 
 *      cmd-name
 * 
 * # output
 * 
 *      command output description
 * 
 */
void dummy_function();

@brechtm, can you double-check that this particular case is fixed with the PR for you as well?

[2bndy5]

I think I found a similar edge case (outlined in jbms/sphinx-immaterial#69), but it would require a different solution regarding a parameter's description's inline nodes' text not getting encapsulated with a paragraph node.

[brechtm]

@jakobandersen I tested with your fix-literal-in-paragraph branch, and it does at least fix building the PDF for the Sphinx project attached to brechtm/rinohtype#312. 👍

[jakobandersen]

I think I found a similar edge case (outlined in jbms/sphinx-immaterial#69), but it would require a different solution regarding a parameter's description's inline nodes' text not getting encapsulated with a paragraph node.

It indeed sounds like some doctree cleanup might be needed. Please open a separate issue to discuss details.