From: Vladimír Vondruš Date: Mon, 16 Sep 2024 17:47:23 +0000 (+0200) Subject: documentation/doxygen: properly handle and everywhere. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=af7bc2592dd0f249a5bd5e04247f71af83cc9c9c;p=blog.git documentation/doxygen: properly handle and everywhere. Insufficient testing in 2b57d535dfddbee13cb30ad352c42e68e7915553 and before led to this (hitting the unreachable assert below), fortunately looking at code coverage revealed the "more than three levels of Markdown headings" message was never tested properly. --- diff --git a/documentation/doxygen.py b/documentation/doxygen.py index 88a2d80d..5b0d8e88 100755 --- a/documentation/doxygen.py +++ b/documentation/doxygen.py @@ -699,7 +699,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. tag = 'h5' elif element.tag == 'sect3': tag = 'h6' - elif element.tag == 'sect4': + elif element.tag in ['sect4', 'sect5', 'sect6']: tag = 'h6' logging.warning("{}: more than three levels of sections in member descriptions are not supported, stopping at
".format(state.current)) elif not element.tag == 'simplesect': # pragma: no cover diff --git a/documentation/test_doxygen/contents_sections_headings/Warnings.h b/documentation/test_doxygen/contents_sections_headings/Warnings.h index ce4a8a81..257fc2c5 100644 --- a/documentation/test_doxygen/contents_sections_headings/Warnings.h +++ b/documentation/test_doxygen/contents_sections_headings/Warnings.h @@ -5,8 +5,18 @@ /** @brief This produces warnings +# Markdown heading 1 + +## Markdown heading 2 + +### Markdown heading 3 + #### Markdown heading 4 that's rendered the same as 3 +##### Markdown heading 5 that's rendered the same as 3 + +###### Markdown heading 6 that's rendered the same as 3 + Markdown heading, underlined, is misparsed ########################################## diff --git a/documentation/test_doxygen/contents_sections_headings/Warnings_8h-110.html b/documentation/test_doxygen/contents_sections_headings/Warnings_8h-110.html index 51c0aef4..67834d3d 100644 --- a/documentation/test_doxygen/contents_sections_headings/Warnings_8h-110.html +++ b/documentation/test_doxygen/contents_sections_headings/Warnings_8h-110.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 1

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

Markdown heading 5 that's rendered the same as 3
Markdown heading 6 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 4ec185da..6210eb01 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 1

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

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

diff --git a/documentation/test_doxygen/contents_sections_headings/warnings-110.html b/documentation/test_doxygen/contents_sections_headings/warnings-110.html index 6410f51b..b36b4608 100644 --- a/documentation/test_doxygen/contents_sections_headings/warnings-110.html +++ b/documentation/test_doxygen/contents_sections_headings/warnings-110.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/contents_sections_headings/warnings.html b/documentation/test_doxygen/contents_sections_headings/warnings.html index e03d348f..0d1c16a0 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 996b5aba..06dc2f1f 100644 --- a/documentation/test_doxygen/test_contents.py +++ b/documentation/test_doxygen/test_contents.py @@ -481,6 +481,9 @@ class SectionsHeadings(IntegrationTestCase): page = 'warnings.html' file = 'Warnings_8h.html' output = [ + # Once for every extra level + "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", + "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", "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
", ] @@ -488,7 +491,10 @@ class SectionsHeadings(IntegrationTestCase): page = 'warnings-110.html' file = 'Warnings_8h-110.html' output = [ + # Once for the first extra level, then two more for another "WARNING:root:Warnings_8h.xml: more than three levels of sections in member descriptions are not supported, stopping at
", + 'WARNING:root:Warnings_8h.xml: more than three levels of Markdown headings in member descriptions are not supported, stopping at
', + 'WARNING:root:Warnings_8h.xml: more than three levels of Markdown headings 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",