From 2eb544cac8b53be176994f92d987e9fed157b076 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Vladim=C3=ADr=20Vondru=C5=A1?= Date: Thu, 13 Sep 2018 13:16:23 +0200 Subject: [PATCH] doxygen: as usual, I found more Doxygen bugs while fixing other stuff. This usual thing in Markdown files, for example: Hello world ########### is parsed as a paragraph and a 11th level heading with no title. UHHMAZING, isn't it. Because of that, I'm no longer asserting on too large heading levels but instead trying to provide helpful warning messages for the user. --- doxygen/dox2html5.py | 55 +++++++++---------- .../Doxyfile | 2 +- .../File.h | 13 ++++- .../File_8h.html | 13 ++++- .../contents_sections_headings/index.html | 31 +++++++++++ .../test/contents_sections_headings/input.dox | 34 ++++++++++++ .../warnings.html | 2 +- doxygen/test/contents_typography/index.html | 6 +- doxygen/test/contents_typography/input.dox | 24 ++------ doxygen/test/test_contents.py | 16 ++++-- 10 files changed, 134 insertions(+), 62 deletions(-) rename doxygen/test/{contents_section_in_function => contents_sections_headings}/Doxyfile (87%) rename doxygen/test/{contents_section_in_function => contents_sections_headings}/File.h (63%) rename doxygen/test/{contents_section_in_function => contents_sections_headings}/File_8h.html (73%) create mode 100644 doxygen/test/contents_sections_headings/index.html create mode 100644 doxygen/test/contents_sections_headings/input.dox rename doxygen/test/{contents_typography => contents_sections_headings}/warnings.html (84%) diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 7f3e8bb2..4a6456a6 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -732,37 +732,36 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. assert element.tag == 'para' # is inside a paragraph :/ has_block_elements = True - # Top-level description - if state.parsing_toplevel_desc: - if i.attrib['level'] == '1': - tag = 'h2' - elif i.attrib['level'] == '2': - tag = 'h3' - elif i.attrib['level'] == '3': - tag = 'h4' - elif i.attrib['level'] == '4': - tag = 'h5' - else: # pragma: no cover - assert False + # 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)) - # 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

for function - # header, which is inside

for detailed definition section, so - # it needs to be

and below else: - if i.attrib['level'] == '1': - tag = 'h4' - elif i.attrib['level'] == '2': - tag = 'h5' - elif i.attrib['level'] in ['3', '4']: - tag = 'h6' # there is no - else: # pragma: no cover - assert False + h_tag_level = int(i.attrib['level']) + assert h_tag_level > 0 + + # Top-level description can have 5 levels (first level used for + # page title), so it needs to be

and below + if state.parsing_toplevel_desc: + h_tag_level += 1 + if h_tag_level > 6: + h_tag_level = 6 + logging.warning("{}: more than five levels of Markdown headings for top-level docs are not supported, stopping at

".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

for function + # header, which is inside

for detailed definition section, + # so it needs to be

and below + else: + h_tag_level += 3 + if h_tag_level > 6: + h_tag_level = 6 + logging.warning("{}: more than three levels of Markdown headings in member descriptions are not supported, stopping at

".format(state.current)) - out.parsed += '<{0}>{1}'.format(tag, html.escape(i.text)) + out.parsed += '{1}'.format(h_tag_level, html.escape(i.text)) elif i.tag == 'para': assert element.tag != 'para' # should be top-level block element diff --git a/doxygen/test/contents_section_in_function/Doxyfile b/doxygen/test/contents_sections_headings/Doxyfile similarity index 87% rename from doxygen/test/contents_section_in_function/Doxyfile rename to doxygen/test/contents_sections_headings/Doxyfile index 49e476ec..b74ee57c 100644 --- a/doxygen/test/contents_section_in_function/Doxyfile +++ b/doxygen/test/contents_sections_headings/Doxyfile @@ -1,4 +1,4 @@ -INPUT = File.h +INPUT = File.h input.dox QUIET = YES GENERATE_HTML = NO GENERATE_LATEX = NO diff --git a/doxygen/test/contents_section_in_function/File.h b/doxygen/test/contents_sections_headings/File.h similarity index 63% rename from doxygen/test/contents_section_in_function/File.h rename to doxygen/test/contents_sections_headings/File.h index 33a7dbc4..3690b455 100644 --- a/doxygen/test/contents_section_in_function/File.h +++ b/doxygen/test/contents_sections_headings/File.h @@ -11,8 +11,6 @@ ### A third-level header -#### A fourth-level header - @section foo-usage Usage This is usage. @@ -29,3 +27,14 @@ Mooore. @return Does not return anything. */ void foo(int bar); + +/** +@brief This produces warnings + +#### Markdown heading 4 that's rendered the same as 3 + +Markdown heading, underlined, is misparsed +########################################## + +*/ +void bar(int foo); diff --git a/doxygen/test/contents_section_in_function/File_8h.html b/doxygen/test/contents_sections_headings/File_8h.html similarity index 73% rename from doxygen/test/contents_section_in_function/File_8h.html rename to doxygen/test/contents_sections_headings/File_8h.html index 3a6c4d86..3d415643 100644 --- a/doxygen/test/contents_section_in_function/File_8h.html +++ b/doxygen/test/contents_sections_headings/File_8h.html @@ -41,6 +41,10 @@ void foo(int bar)
A function.
+
+ void bar(int foo) +
+
This produces warnings.
@@ -67,7 +71,14 @@ -

A top-level header

A second-level header
A third-level header
A fourth-level header

Usage

This is usage.

More

A subsection.

More.

Mooore.

+

A top-level header

A second-level header
A third-level header

Usage

This is usage.

More

A subsection.

More.

Mooore.

+
+
+

+ 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/doxygen/test/contents_sections_headings/index.html b/doxygen/test/contents_sections_headings/index.html new file mode 100644 index 00000000..207ac687 --- /dev/null +++ b/doxygen/test/contents_sections_headings/index.html @@ -0,0 +1,31 @@ + + + + + My Project + + + + + +
+
+ + diff --git a/doxygen/test/contents_sections_headings/input.dox b/doxygen/test/contents_sections_headings/input.dox new file mode 100644 index 00000000..14d93a4e --- /dev/null +++ b/doxygen/test/contents_sections_headings/input.dox @@ -0,0 +1,34 @@ +/** @mainpage + +@section section Page section + +Text. + +@subsection subsection Page subsection + +Text! + +@subsubsection subsubsection Sub-sub section + +Reference to @ref subsection "a page subsection" and @ref subsubsection. + +*/ + +/** @page warnings 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 +########################################## + +*/ diff --git a/doxygen/test/contents_typography/warnings.html b/doxygen/test/contents_sections_headings/warnings.html similarity index 84% rename from doxygen/test/contents_typography/warnings.html rename to doxygen/test/contents_sections_headings/warnings.html index b1d8baff..eef8cc98 100644 --- a/doxygen/test/contents_typography/warnings.html +++ b/doxygen/test/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 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/doxygen/test/contents_typography/index.html b/doxygen/test/contents_typography/index.html index ccbce771..c8e529b8 100644 --- a/doxygen/test/contents_typography/index.html +++ b/doxygen/test/contents_typography/index.html @@ -22,10 +22,10 @@

My Project

-

Page section

A blockquote.

Preformatted text.
-

Paragraph
with
explicit
line
breaks.

Differently
+
A blockquote.
Preformatted text.
+
Paragraph
with
explicit
line
breaks.
Page section
Differently
   preformatted
-text.
Page subsection
  • Unordered
  • list
  • of
    • nested
    • items
  • and back
Sub-sub section
  1. Ordered
  2. list
  3. of
    1. nested
    2. items
  4. and back
 This is a typewriter text, emphasis and bold. Emphasis with typewriter and bold nested. http://google.com and URL. Small text. En-dash – and em-dash —. Reference to a Page subsection. Named reference with special characters in title: » Warnings «. Reference with escaped characters in title: <anchor>.
Empty elements:
Above is a horizontal line.

+text.
  • Unordered
  • list
  • of
    • nested
    • items
  • and back
  1. Ordered
  2. list
  3. of
    1. nested
    2. items
  4. and back
 This is a typewriter text, emphasis and bold. Emphasis with typewriter and bold nested. http://google.com and URL. Small text. En-dash – and em-dash —. Reference to a Page section. Named reference with special characters in title: » Warnings «. Reference with escaped characters in title: <anchor>.
Empty elements:
Above is a horizontal line.

       
     
   
diff --git a/doxygen/test/contents_typography/input.dox b/doxygen/test/contents_typography/input.dox
index 86d248de..bf3ec484 100644
--- a/doxygen/test/contents_typography/input.dox
+++ b/doxygen/test/contents_typography/input.dox
@@ -1,19 +1,17 @@
 /** @mainpage
 
-@section section Page section
-
 > A blockquote.
 
     Preformatted text.
 
 Paragraph \n with \n explicit \n line \n breaks.
 
+@section section Page section
+
 
Differently
   preformatted
 text.

 
-@subsection subsection Page subsection
-
 -   Unordered
 -   list
 -   of
@@ -21,8 +19,6 @@ text.
     -   items
 -   and back
 
-@subsubsection subsubsection Sub-sub section
-
 1.  Ordered
 2.  list
 3.  of
@@ -35,8 +31,8 @@ text.
 This is a `typewriter text`, *emphasis* and **bold**. Emphasis with
 typewriter and bold nested. http://google.com
 and [URL](http://google.com). Small *text*. En-dash -- and
-em-dash ---. Reference to a @ref subsection. Named reference with special
-characters in title: @ref warnings "» Warnings «". Reference with
+em-dash ---. Reference to a @ref section. Named reference with special
+characters in title: @ref section "» Warnings «". Reference with
 escaped characters in title: @ref an-anchor "".
 
 Empty elements:    
 
@@ -46,15 +42,3 @@ Empty elements: