From: Vladimír Vondruš Date: Wed, 13 Dec 2017 20:22:08 +0000 (+0100) Subject: doxygen: code after a note and ending a paragraph is a block one. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=be13d022d9b3ed3e719dae19f5ea6cdea372457e;p=blog.git 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 2fb3a297..1171077c 100755 --- 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() + '' @@ -238,15 +239,28 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # 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

and use 

:
-                # - 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
+        #  tag) could affect it in this iteration.
+        if i.tag != 'simplesect' and previous_section:
+            previous_section = None
+
         # DOXYGEN  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 55797760..3dcfa983 100644
--- a/doxygen/test/contents_code/index.html
+++ b/doxygen/test/contents_code/index.html
@@ -42,7 +42,7 @@
     // a block
         // that is indented
     // but has a lot of trailing whitespace which should be removed
-}

Code block inside a list (has to be done using HTML):

+}
// this is a new block

The constexpr functions are pure.

Code block inside a list (has to be done using HTML):

diff --git a/doxygen/test/contents_code/input.dox b/doxygen/test/contents_code/input.dox index 29b423b4..299c37e9 100644 --- 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):