From: Vladimír Vondruš Date: Wed, 13 Dec 2017 19:46:18 +0000 (+0100) Subject: doxygen: implemented section merging. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=243fcf845926be357160563c5ec9c2a6e16590f5;p=blog.git doxygen: implemented section merging. So multiple adjacent \attention, \note etc. paragraph of the same kind are now merged into one, to be consistent with HTML output. Works also with code blocks. --- diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 38d4af5d..2fb3a297 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -165,12 +165,23 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. paragraph_count = 0 has_block_elements = False + # So we are able to merge content of adjacent sections. Tuple of (tag, + # kind), set only if there is no i.tail, reset in the next iteration. + previous_section = None + i: ET.Element for i in 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. + if previous_section and i.tag != 'simplesect': + previous_section = None + assert not out.write_paragraph_close_tag + out.parsed = out.parsed.rstrip() + '' + # DOXYGEN PATCHING 2/4 # # Upon encountering a block element nested in , we need to act. @@ -401,22 +412,43 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.return_value = parse_desc(state, i) else: has_block_elements = True - if i.attrib['kind'] == 'see': - out.parsed += '

Note

' - elif i.attrib['kind'] == 'attention': - out.parsed += '

Attention

' - else: # pragma: no cover - out.parsed += '' + + # Not continuing with a section from before, put a header in + if not previous_section or previous_section != i.attrib['kind']: + if i.attrib['kind'] == 'see': + out.parsed += '

Note

' + elif i.attrib['kind'] == 'attention': + out.parsed += '' + previous_section = None + + # Otherwise put the responsibility on the next iteration, maybe + # there are more paragraphs that should be merged + else: + previous_section = i.attrib['kind'] elif i.tag == 'xrefsect': assert element.tag == 'para' # is inside a paragraph :/ has_block_elements = True + # Not merging these, as every has usually a different ID each. (And + # apparently Doxygen is able to merge them *but only if* they + # describe some symbol, not on a page.) id = i.attrib['id'] match = xref_id_rx.match(id) file = match.group(1) @@ -656,6 +688,12 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. tail = tail.lstrip() out.parsed += tail + # A section was left open in the last iteration, close it. Expect that + # there was nothing after that would mess with us. + if previous_section: + assert not out.write_paragraph_close_tag + out.parsed = out.parsed.rstrip() + '

' + # Brief description always needs to be single paragraph because we're # sending it out without enclosing

. if element.tag == 'briefdescription': diff --git a/doxygen/test/contents_blocks/Doxyfile b/doxygen/test/contents_blocks/Doxyfile index d64a2386..fea67c7d 100644 --- a/doxygen/test/contents_blocks/Doxyfile +++ b/doxygen/test/contents_blocks/Doxyfile @@ -1,4 +1,4 @@ -INPUT = input.dox +INPUT = input.dox File.h QUIET = YES GENERATE_HTML = NO GENERATE_LATEX = NO diff --git a/doxygen/test/contents_blocks/File.h b/doxygen/test/contents_blocks/File.h new file mode 100644 index 00000000..a17e8541 --- /dev/null +++ b/doxygen/test/contents_blocks/File.h @@ -0,0 +1,11 @@ +/** @file + * @brief A file + */ + +/** +@brief A foo + +@xrefitem old "Old stuff" "Just old" Xrefitem, gets merged +@xrefitem old "Old stuff" "Just old" with this one by Doxygen itself. +*/ +int foo(); diff --git a/doxygen/test/contents_blocks/File_8h.html b/doxygen/test/contents_blocks/File_8h.html new file mode 100644 index 00000000..6f06b63f --- /dev/null +++ b/doxygen/test/contents_blocks/File_8h.html @@ -0,0 +1,85 @@ + + + + + File.h file | My Project + + + + + + +

+ File.h file +

A file.

+ Reference +
- Functions
+

Functions

+ auto foo() -> int +: A foo.

Function documentation

+ int foo() +

A foo.

+ +

+ + + diff --git a/doxygen/test/contents_blocks/index.html b/doxygen/test/contents_blocks/index.html index 32530ac0..f7df9306 100644 --- a/doxygen/test/contents_blocks/index.html +++ b/doxygen/test/contents_blocks/index.html @@ -37,7 +37,7 @@

My Project

First paragraph containing some content.

Paragraph following the sections.

A blockquote

Text right after that blockquote should be a new paragraph.

A simple
List
1. With one line
2. for each
item, so paragraphs are removed

A simple
List
1. With the sublist delimited
2. by blank lines
should behave the same as above

A new list
of multiple
paragraphs.
Another item
- A sub list
  Another paragraph

A paragraph after that list.

Table header	Another	Third
Cell	Another cell	3rd
Next row		This
is a table	really	yes.

First paragraph containing some content.

Paragraph following the sections.

A blockquote

Text right after that blockquote should be a new paragraph.

A simple
List
1. With one line
2. for each
item, so paragraphs are removed

A simple
List
1. With the sublist delimited
2. by blank lines
should behave the same as above

A new list
of multiple
paragraphs.
Another item
- A sub list
  Another paragraph

A paragraph after that list.

Table header	Another	Third
Cell	Another cell	3rd
Next row		This
is a table	really	yes.

diff --git a/doxygen/test/contents_blocks/input.dox b/doxygen/test/contents_blocks/input.dox index 5b026f25..ba1a7cc0 100644 --- a/doxygen/test/contents_blocks/input.dox +++ b/doxygen/test/contents_blocks/input.dox @@ -59,6 +59,19 @@ Cell | Another cell | 3rd Next row | | This is a table | *really* | yes. +@attention + Attention, first paragraph. +@attention + Attention, second paragraph. +@attention + Attention, third paragraph. +@note + A note, not merged with the above. + +@xrefitem old "Old stuff" "Just old" This is not merged. + +@xrefitem old "Old stuff" "Just old" With this. Only on the listing page. + */ /** @page other Other page diff --git a/doxygen/test/contents_blocks/old.html b/doxygen/test/contents_blocks/old.html new file mode 100644 index 00000000..82c9f960 --- /dev/null +++ b/doxygen/test/contents_blocks/old.html @@ -0,0 +1,55 @@ + + + + + Just old | My Project + + + + + + +

+ Just old +

Member foo ()

Xrefitem, gets merged

with this one by Doxygen itself.

page Main Page

This is old.

This is not merged.

With this. Only on the listing page.

+ + + diff --git a/doxygen/test/contents_code/index.html b/doxygen/test/contents_code/index.html index d6d42604..55797760 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):

A paragraph.
```
#include <os>
```
Another paragraph.
Yet another
A single paragraph, rendered without the wrapping tag

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

A paragraph.
```
#include <os>
```
Another paragraph.
Yet another
A single paragraph, rendered without the wrapping tag

Note

Code block inside a note:

// code block

Another paragraph of that note.

diff --git a/doxygen/test/contents_code/input.dox b/doxygen/test/contents_code/input.dox index 76aa4b63..29b423b4 100644 --- a/doxygen/test/contents_code/input.dox +++ b/doxygen/test/contents_code/input.dox @@ -39,6 +39,15 @@ Code block inside a list (has to be done using HTML):

A single paragraph, rendered without the wrapping tag

+@note + Code block inside a note: +@note + @code{.cpp} + // code block + @endcode +@note + Another paragraph of that note. + */ /** @page warnings Code that produces warnings diff --git a/doxygen/test/test_contents.py b/doxygen/test/test_contents.py index 03347c02..03fe0f9a 100644 --- a/doxygen/test/test_contents.py +++ b/doxygen/test/test_contents.py @@ -54,6 +54,13 @@ class Blocks(IntegrationTestCase): self.run_dox2html5(wildcard='todo.xml') self.assertEqual(*self.actual_expected_contents('todo.html')) + def test_builtin_xrefitem_merging(self): + # Multiple xrefitems should be merged into one here + self.run_dox2html5(wildcard='File_8h.xml') + self.run_dox2html5(wildcard='old.xml') + self.assertEqual(*self.actual_expected_contents('File_8h.html')) + self.assertEqual(*self.actual_expected_contents('old.html')) + class Code(IntegrationTestCase): def __init__(self, *args, **kwargs): super().__init__(__file__, 'code', *args, **kwargs)