From: Vladimír Vondruš Date: Fri, 13 Sep 2024 21:23:25 +0000 (+0200) Subject: documentation/doxygen: Doxygen 1.12 can produce up to . X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=f82127309d73ae6c125b16394457a49f664d854a;p=blog.git documentation/doxygen: Doxygen 1.12 can produce up to . And is slightly less broken when encountering Markdown headers where it's not #'s at the start of the line but underneath. --- diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 9a88dcea..c242416d 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -597,8 +597,9 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.parsed += '

' out.write_paragraph_close_tag = True - # Block elements - if i.tag in ['sect1', 'sect2', 'sect3', 'sect4']: + # Block elements. Until Doxygen 1.11 it was at most , 1.12 seems + # to have up to 6: https://github.com/doxygen/doxygen/issues/11016 + if i.tag in ['sect1', 'sect2', 'sect3', 'sect4', 'sect5', 'sect6']: assert element.tag != 'para' # should be top-level block element has_block_elements = True @@ -637,6 +638,11 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. tag = 'h4' elif element.tag == 'sect4': tag = 'h5' + elif element.tag == 'sect5': + tag = 'h6' + elif element.tag == 'sect6': + tag = 'h6' + logging.warning("{}: more than five levels of sections are not supported, stopping at

".format(state.current)) elif not element.tag == 'simplesect': # pragma: no cover assert False @@ -672,7 +678,11 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.parsed += '<{0} id="{1}">{2}'.format(tag, id, title) # Apparently, in 1.8.18, is used for Markdown headers only if - # we run out of sect1-4 tags. Eh, what the hell. + # we run out of sect1-4 tags. Which also happens when there's a heading + # with a ####### underline. In 1.12 it doesn't produce a , and + # instead just puts the #'s to the output verbatim. Which means we + # can't warn for that. See test_contents.SectionsHeadings for repro + # cases. elif i.tag == 'heading': assert element.tag == 'para' # is inside a paragraph :/ has_block_elements = True diff --git a/documentation/test_doxygen/contents_sections_headings/Warnings_8h-111.html b/documentation/test_doxygen/contents_sections_headings/Warnings_8h-111.html new file mode 100644 index 00000000..51c0aef4 --- /dev/null +++ b/documentation/test_doxygen/contents_sections_headings/Warnings_8h-111.html @@ -0,0 +1,61 @@ + + + + + Warnings.h file | My Project + + + + + +
+
+
+
+
+

+ Warnings.h file +

+

A file producing warnings.

+ +
+

Functions

+
+
+ void bar(int foo) +
+
This produces warnings.
+
+
+
+

Function documentation

+
+

+ void bar(int foo) +

+

This produces warnings.

+
Markdown heading 4 that's rendered the same as 3

Markdown heading, underlined, is misparsed

+
+
+
+
+
+
+ + diff --git a/documentation/test_doxygen/contents_sections_headings/Warnings_8h.html b/documentation/test_doxygen/contents_sections_headings/Warnings_8h.html index 51c0aef4..4ec185da 100644 --- a/documentation/test_doxygen/contents_sections_headings/Warnings_8h.html +++ b/documentation/test_doxygen/contents_sections_headings/Warnings_8h.html @@ -50,7 +50,7 @@ void bar(int foo)

This produces warnings.

-
Markdown heading 4 that's rendered the same as 3

Markdown heading, underlined, is misparsed

+
Markdown heading 4 that's rendered the same as 3

Markdown heading, underlined, is misparsed ##########################################

diff --git a/documentation/test_doxygen/contents_sections_headings/warnings-111.html b/documentation/test_doxygen/contents_sections_headings/warnings-111.html new file mode 100644 index 00000000..6410f51b --- /dev/null +++ b/documentation/test_doxygen/contents_sections_headings/warnings-111.html @@ -0,0 +1,31 @@ + + + + + Content that produces warnings | My Project + + + + + +
+
+ + diff --git a/documentation/test_doxygen/contents_sections_headings/warnings.html b/documentation/test_doxygen/contents_sections_headings/warnings.html index 6410f51b..e03d348f 100644 --- a/documentation/test_doxygen/contents_sections_headings/warnings.html +++ b/documentation/test_doxygen/contents_sections_headings/warnings.html @@ -22,7 +22,7 @@

Content that produces warnings

-

Markdown heading 1

Markdown heading 2

Markdown heading 3

Markdown heading 4

Markdown heading 5
Markdown heading 6 that's rendered the same as 5

Markdown heading, underlined, is misparsed

+

Markdown heading 1

Markdown heading 2

Markdown heading 3

Markdown heading 4
Markdown heading 5
Markdown heading 6 that's rendered the same as 5

Markdown heading, underlined, is misparsed ##########################################

diff --git a/documentation/test_doxygen/test_contents.py b/documentation/test_doxygen/test_contents.py index cf9e7275..5c42767a 100644 --- a/documentation/test_doxygen/test_contents.py +++ b/documentation/test_doxygen/test_contents.py @@ -407,14 +407,28 @@ class SectionsHeadings(IntegrationTestCase): with self.assertLogs() as cm: self.run_doxygen(wildcard='*arnings*.xml') - self.assertEqual(*self.actual_expected_contents('warnings.html')) - self.assertEqual(*self.actual_expected_contents('Warnings_8h.html')) - self.assertEqual(cm.output, [ - "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", - "WARNING:root:Warnings_8h.xml: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead", - "WARNING:root:warnings.xml: more than five levels of Markdown headings for top-level docs are not supported, stopping at
", - "WARNING:root:warnings.xml: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead", - ]) + # https://github.com/doxygen/doxygen/issues/11016, merged into 1.12, is + # responsible I think. It got better, yes. + if parse_version(doxygen_version()) >= (1, 12): + page = 'warnings.html' + file = 'Warnings_8h.html' + output = [ + "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", + "WARNING:root:warnings.xml: more than five levels of sections are not supported, stopping at
", + ] + else: + page = 'warnings-111.html' + file = 'Warnings_8h-111.html' + output = [ + "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", + "WARNING:root:Warnings_8h.xml: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead", + "WARNING:root:warnings.xml: more than five levels of Markdown headings for top-level docs are not supported, stopping at
", + "WARNING:root:warnings.xml: a Markdown heading underline was apparently misparsed by Doxygen, prefix the headings with # instead", + ] + + self.assertEqual(*self.actual_expected_contents('warnings.html', page)) + self.assertEqual(*self.actual_expected_contents('Warnings_8h.html', file)) + self.assertEqual(cm.output, output) class AnchorInBothGroupAndNamespace(IntegrationTestCase): def test(self):