From 6b9b5ac848b8e06a129847fca02998f19b3ae670 Mon Sep 17 00:00:00 2001
From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= <mosra@centrum.cz>
Date: Thu, 7 May 2020 16:57:07 +0200
Subject: [PATCH] documentation/doxygen: 1.8.18 parses Markdown differently, it
 seems.

Better, even. Unheard of.
---
 documentation/doxygen.py                          | 15 +++++++++------
 .../contents_sections_headings/File_8h.html       |  4 ++--
 .../contents_sections_headings/warnings.html      |  2 +-
 3 files changed, 12 insertions(+), 9 deletions(-)

diff --git a/documentation/doxygen.py b/documentation/doxygen.py
index 03ca56a4..4b600f1f 100755
--- a/documentation/doxygen.py
+++ b/documentation/doxygen.py
@@ -506,7 +506,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                 out.write_paragraph_close_tag = True
 
         # Block elements
-        if i.tag in ['sect1', 'sect2', 'sect3']:
+        if i.tag in ['sect1', 'sect2', 'sect3', 'sect4']:
             assert element.tag != 'para' # should be top-level block element
             has_block_elements = True
 
@@ -543,6 +543,8 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                     tag = 'h3'
                 elif element.tag == 'sect3':
                     tag = 'h4'
+                elif element.tag == 'sect4':
+                    tag = 'h5'
                 elif not element.tag == 'simplesect': # pragma: no cover
                     assert False
 
@@ -556,6 +558,9 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                     tag = 'h5'
                 elif element.tag == 'sect3':
                     tag = 'h6'
+                elif element.tag == 'sect4':
+                    tag = 'h6'
+                    logging.warning("{}: more than three levels of sections in member descriptions are not supported, stopping at <h6>".format(state.current))
                 elif not element.tag == 'simplesect': # pragma: no cover
                     assert False
 
@@ -574,13 +579,15 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                 else:
                     out.parsed += '<{0} id="{1}">{2}</{0}>'.format(tag, id, title)
 
+        # Apparently, in 1.8.18, <heading> is used for Markdown headers only if
+        # we run out of sect1-4 tags. Eh, what the hell.
         elif i.tag == 'heading':
             assert element.tag == 'para' # is inside a paragraph :/
             has_block_elements = True
 
             # Do not print anything if there are no contents
             if not i.text:
-                logging.warning("{}: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead (or better, use @section for properly generated TOC)".format(state.current))
+                logging.warning("{}: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead".format(state.current))
 
             else:
                 h_tag_level = int(i.attrib['level'])
@@ -594,10 +601,6 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                         h_tag_level = 6
                         logging.warning("{}: more than five levels of Markdown headings for top-level docs are not supported, stopping at <h6>".format(state.current))
 
-                    # Emit this warning only in top-level desc, TOC is not
-                    # generated for function/enum/... descriptions
-                    logging.warning("{}: prefer @section over Markdown heading for properly generated TOC".format(state.current))
-
                 # Function/enum/... descriptions are inside <h3> for function
                 # header, which is inside <h2> for detailed definition section,
                 # so it needs to be <h4> and below
diff --git a/documentation/test_doxygen/contents_sections_headings/File_8h.html b/documentation/test_doxygen/contents_sections_headings/File_8h.html
index 67f3af01..dc347b42 100644
--- a/documentation/test_doxygen/contents_sections_headings/File_8h.html
+++ b/documentation/test_doxygen/contents_sections_headings/File_8h.html
@@ -71,14 +71,14 @@
                 </tr>
               </tfoot>
             </table>
-<h4>A top-level header</h4><h5>A second-level header</h5><h6>A third-level header</h6><h4 id="foo-usage">Usage</h4><p>This is usage.</p><h5 id="foo-usage-more">More</h5><p>A subsection.</p><h6 id="foo-usage-more-more">More.</h6><p>Mooore.</p>
+<h4 id="autotoc_md0">A top-level header</h4><h5 id="autotoc_md1">A second-level header</h5><h6 id="autotoc_md2">A third-level header</h6><h4 id="foo-usage">Usage</h4><p>This is usage.</p><h5 id="foo-usage-more">More</h5><p>A subsection.</p><h6 id="foo-usage-more-more">More.</h6><p>Mooore.</p>
           </div></section>
           <section class="m-doc-details" id="ac03b94e5ed1aeeba4c9d31498e9a767a"><div>
             <h3>
               <span class="m-doc-wrap-bumper">void </span><span class="m-doc-wrap"><span class="m-doc-wrap-bumper"><a href="#ac03b94e5ed1aeeba4c9d31498e9a767a" class="m-doc-self">bar</a>(</span><span class="m-doc-wrap">int foo)</span></span>
             </h3>
             <p>This produces warnings.</p>
-<h6>Markdown heading 4 that&#x27;s rendered the same as 3</h6><p>Markdown heading, underlined, is misparsed</p>
+<h6 id="autotoc_md3">Markdown heading 4 that&#x27;s rendered the same as 3</h6><p>Markdown heading, underlined, is misparsed</p>
           </div></section>
         </section>
       </div>
diff --git a/documentation/test_doxygen/contents_sections_headings/warnings.html b/documentation/test_doxygen/contents_sections_headings/warnings.html
index e35ca93f..6410f51b 100644
--- a/documentation/test_doxygen/contents_sections_headings/warnings.html
+++ b/documentation/test_doxygen/contents_sections_headings/warnings.html
@@ -22,7 +22,7 @@
         <h1>
           Content that produces warnings
         </h1>
-<h2>Markdown heading 1</h2><h3>Markdown heading 2</h3><h4>Markdown heading 3</h4><h5>Markdown heading 4</h5><h6>Markdown heading 5</h6><h6>Markdown heading 6 that&#x27;s rendered the same as 5</h6><p>Markdown heading, underlined, is misparsed</p>
+<section id="autotoc_md4"><h2><a href="#autotoc_md4">Markdown heading 1</a></h2><section id="autotoc_md5"><h3><a href="#autotoc_md5">Markdown heading 2</a></h3><section id="autotoc_md6"><h4><a href="#autotoc_md6">Markdown heading 3</a></h4><section id="autotoc_md7"><h5><a href="#autotoc_md7">Markdown heading 4</a></h5><p><a name="autotoc_md8"></a></p><h6>Markdown heading 5</h6><h6>Markdown heading 6 that&#x27;s rendered the same as 5</h6><p>Markdown heading, underlined, is misparsed</p></section></section></section></section>
       </div>
     </div>
   </div>
-- 
2.30.2