doxygen: code after a note and ending a paragraph is a block one.

Doxygen is stupid and doesn't delimit end of a note from the following
code block with a new paragraph. Ugh. Everything is broken here in its
own special way.

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index 2fb3a297802bdaa65bb91914913ab2e42b7da1b4..1171077c1ec15b03bfc892b13bda0cbbfb7a0f5f 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -170,15 +170,16 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
     previous_section = None
 
     i: ET.Element
-    for i in element:
+    for index, i in enumerate(element):
         # State used later
         code_block = None
         formula_block = None
 
         # A section was left open, but there's nothing to continue it, close
         # it. Expect that there was nothing after that would mess with us.
+        # Don't reset it back to None just yet, as inline/block code
+        # autodetection needs it.
         if previous_section and i.tag != 'simplesect':
-            previous_section = None
             assert not out.write_paragraph_close_tag
             out.parsed = out.parsed.rstrip() + '</aside>'
 
@@ -238,15 +239,28 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
 
             # <programlisting> is autodetected to be either block or inline
             elif i.tag == 'programlisting':
+                element_children_count = len([listing for listing in element])
+
                 # If it seems to be a standalone code paragraph, don't wrap it
                 # in <p> and use <pre>:
-                # - is either alone in the paragraph, with no text or other
-                #   elements around
-                # - or is a code snippet (filename instead of just .ext).
-                #   Doxygen unfortunately doesn't put @snippet in its own
-                #   paragraph even if it's separated by blank lines. It does so
-                #   for @include and related, though.
-                if ((not element.text or not element.text.strip()) and (not i.tail or not i.tail.strip()) and len([listing for listing in element]) == 1) or ('filename' in i.attrib and not i.attrib['filename'].startswith('.')):
+                if (
+                    # It's either alone in the paragraph, with no text or other
+                    # elements around, or
+                    ((not element.text or not element.text.strip()) and (not i.tail or not i.tail.strip()) and element_children_count == 1) or
+
+                    # is a code snippet, i.e. filename instead of just .ext
+                    # (Doxygen unfortunately doesn't put @snippet in its own
+                    # paragraph even if it's separated by blank lines. It does
+                    # so for @include and related, though.)
+                    ('filename' in i.attrib and not i.attrib['filename'].startswith('.')) or
+
+                    # or is code right after a note/attention/... section,
+                    # there's no text after and it's the last thing in the
+                    # paragraph (Doxygen ALSO doesn't separate end of a section
+                    # and begin of a code block by a paragraph even if there is
+                    # a blank line.)
+                    (previous_section and (not i.tail or not i.tail.strip()) and index + 1 == element_children_count)
+                ):
                     end_previous_paragraph = True
                     code_block = True
 
@@ -664,6 +678,12 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
         else: # pragma: no cover
             logging.warning("Ignoring <{}> in desc".format(i.tag))
 
+        # Now we can reset previous_section to None, nobody needs it anymore.
+        # Of course we're resetting it only in case nothing else (such as the
+        # <simplesect> tag) could affect it in this iteration.
+        if i.tag != 'simplesect' and previous_section:
+            previous_section = None
+
         # DOXYGEN <PARA> PATCHING 4/4
         #
         # Besides putting notes and blockquotes and shit inside paragraphs,

diff --git a/doxygen/test/contents_code/index.html b/doxygen/test/contents_code/index.html
index 55797760ff5255d2fad57a903d0d260fba55ebf8..3dcfa983fd0eebf7167b552b147afa7d99b5aef2 100644 (file)
--- a/doxygen/test/contents_code/index.html
+++ b/doxygen/test/contents_code/index.html
@@ -42,7 +42,7 @@
     <span class="c1">// a block</span>
         <span class="c1">// that is indented</span>
     <span class="c1">// but has a lot of trailing whitespace which should be removed</span>
-<span class="p">}</span></pre><p>Code block inside a list (has to be done using HTML):</p><ul><li><p>A paragraph.</p><pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;os&gt;</span><span class="cp"></span></pre></li><li><p>Another paragraph.</p><p>Yet another</p></li><li>A single paragraph, rendered without the wrapping tag</li></ul><aside class="m-note m-info"><h4>Note</h4><p>Code block inside a note:</p><pre class="m-code"><span class="c1">// code block</span></pre><p>Another paragraph of that note.</p></aside>
+<span class="p">}</span></pre><aside class="m-note m-info"><h4>Note</h4><p>Code block after a note doesn&#x27;t start a new paragraph in the XML but should be treated as a block:</p></aside><pre class="m-code"><span class="c1">// this is a new block</span></pre><aside class="m-note m-warning"><h4>Attention</h4><p>Inline code after a note should not be treated as block, though:</p></aside><p>The <code class="m-code"><span class="k">constexpr</span></code> functions are pure.</p><p>Code block inside a list (has to be done using HTML):</p><ul><li><p>A paragraph.</p><pre class="m-code"><span class="cp">#include</span> <span class="cpf">&lt;os&gt;</span><span class="cp"></span></pre></li><li><p>Another paragraph.</p><p>Yet another</p></li><li>A single paragraph, rendered without the wrapping tag</li></ul><aside class="m-note m-info"><h4>Note</h4><p>Code block inside a note:</p><pre class="m-code"><span class="c1">// code block</span></pre><p>Another paragraph of that note.</p></aside>
       </div>
     </div>
   </div>

diff --git a/doxygen/test/contents_code/input.dox b/doxygen/test/contents_code/input.dox
index 29b423b40a5616720e0d27eafda4784ba6bd2e83..299c37e97be3cd75c035e1a426213ed1b7ff3b22 100644 (file)
--- a/doxygen/test/contents_code/input.dox
+++ b/doxygen/test/contents_code/input.dox
@@ -21,6 +21,17 @@ spaces. But not when it is in (@code{.cpp} std::exit(2); @endcode) parentheses.
 
 @endcode
 
+@note Code block after a note doesn't start a new paragraph in the XML but
+    should be treated as a block:
+
+@code{.cpp}
+// this is a new block
+@endcode
+
+@attention Inline code after a note should not be treated as block, though:
+
+The @code{.cpp} constexpr @endcode functions are pure.
+
 Code block inside a list (has to be done using HTML):
 
 <ul>