synopsis is inconsistent with doxygen+breathe

[2bndy5]

This isn't really a problem with this theme's synopsis feature.

I noticed that sphinx_utils.summarize_element_text() may yeild the wrong text because doxygen's XML tends to use different paragraph structure, and breathe simply attempts to output a node tree based on the doxygen XML output (1:1).

So, I'm suggesting a note about synopsis compatibility with other sphinx extensions that don't use nodes.paragraph exactly like sphinx/docutils does.

Example

expected results

useing the RST code

    .. cpp:function:: RF24::RF24(uint32_t _spi_speed=RF24_SPI_SPEED)

        :param _spi_speed: The SPI speed in Hz ie: 1000000 == 1Mhz

            - Users can specify default SPI speed by modifying :c:macro:`RF24_SPI_SPEED` in :file:`RF24_config.h`
        
              - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
              - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
              - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

parameter's pformat() output

<definition>
    <paragraph>
        <inline translatable="True">
            The SPI speed in Hz ie: 1000000 == 1Mhz
            <bullet_list>
                <list_item>
                    <paragraph>
                        Users can specify default SPI speed by modifying
                        <pending_xref refdomain="std" refexplicit="True" refid="RF24__config_8h_1a63ef6fd21b0b83db10e95c0da126d1e2" reftarget="RF24__config_8h_1a63ef6fd21b0b83db10e95c0da126d1e2" reftype="ref">
                            RF24_SPI_SPEED
                         in
                        <pending_xref refdomain="std" refexplicit="True" refid="RF24__config_8h" reftarget="RF24__config_8h" reftype="ref">
                            RF24_config.h
                        <bullet_list>
                            <list_item>
                                <paragraph>
                                    For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
                            <list_item>
                                <paragraph>
                                    Older/Unsupported Arduino devices will use a default clock divider & settings configuration
                            <list_item>
                                <paragraph>
                                    For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

Resulting synopsis for the parameter:

RF24::RF24::RF24::_spi_speed (C++ function parameter) — The SPI speed in Hz ie: 1000000 == 1Mhz

unexpected results (using doxygen+breathe)

using the documented prototype in a header file:

    /**
     * @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz
     * - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h
     *     - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
     *     - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
     *     - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7
     */
    RF24(uint32_t _spi_speed = RF24_SPI_SPEED);

parameter's pformat() output

<definition>
    <paragraph>
        <inline translatable="True">
            <paragraph>
                The SPI speed in Hz ie: 1000000 == 1Mhz
            <bullet_list bullet="-">
                <list_item>
                    <paragraph>
                        Users can specify default SPI speed by modifying
                        <pending_xref cpp:parent_key="<sphinx.domains.cpp.LookupKey object at 0x000001D18B4A8CA0>" refdoc="classRF24" refdomain="c" refexplicit="False" reftarget="RF24_SPI_SPEED" reftype="macro" refwarn="False">
                            <literal classes="xref c c-macro">
                                RF24_SPI_SPEED
                         in
                        <literal classes="file" role="file">
                            RF24_config.h
                    <bullet_list bullet="-">
                        <list_item>
                            <paragraph>
                                For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
                        <list_item>
                            <paragraph>
                                Older/Unsupported Arduino devices will use a default clock divider & settings configuration
                        <list_item>
                            <paragraph>
                                For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

Resulting synopsis for the parameter:

RF24::RF24::RF24::_spi_speed (C++ function parameter) — For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS

[2bndy5]

After examining the pformat() comparison, this issue is somewhat similar to breathe-doc/breathe#827

[jbms]

It seems like it wouldn't necessarily be too difficult to change the synopsis extraction function to also support breathe output.

[2bndy5]

My concern is that this an edge case due to the use of lists in the param description.

[jbms]

I wonder why it isn't finding the paragraph containing The SPI speed in Hz ie: 1000000 == 1Mhz.

[2bndy5]

Could it be because the paragraph is embedded in an inline node?