doxygen: implement remaining kinds of section commands.

In particular:

 - \author, \authors, \copyright
 - \version, \since
 - \date
 - \pre, \post, \invariant
 - \par and RCS entries (`$Id: something $`)

The \par is now also able to append to previous sections of any kind if
its title is omitted.

diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py
index d2d3f4d0ebef48d70ca5af84fe1e6d744ad26138..70a2d0cfb40f3b622e72c4cd1766ae477e2bee5f 100755 (executable)
--- a/doxygen/dox2html5.py
+++ b/doxygen/dox2html5.py
@@ -638,15 +638,18 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                 tag = 'h3'
             elif element.tag == 'sect3':
                 tag = 'h4'
-            else: # pragma: no cover
-                assert False
-            id = extract_id(element)
-            title = html.escape(i.text)
+            elif not element.tag == 'simplesect':
+                assert False # pragma: no cover
+
+            # simplesect titles are handled directly inside simplesect
+            if not element.tag == 'simplesect':
+                id = extract_id(element)
+                title = html.escape(i.text)
 
-            # Populate section info
-            assert not out.section
-            out.section = (id, title, [])
-            out.parsed += '<{0}><a href="#{1}">{2}</a></{0}>'.format(tag, id, title)
+                # Populate section info
+                assert not out.section
+                out.section = (id, title, [])
+                out.parsed += '<{0}><a href="#{1}">{2}</a></{0}>'.format(tag, id, title)
 
         elif i.tag == 'heading':
             assert element.tag == 'para' # is inside a paragraph :/
@@ -794,19 +797,16 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                     logging.warning("{}: superfluous @return section found, ignoring: {} ".format(state.current, ''.join(i.itertext())))
                 else:
                     out.return_value = parse_desc(state, i)
-            # Ignore the RCS strings for now
-            elif i.attrib['kind'] == 'rcs':
-                logging.warning("{}: ignoring {} kind of <simplesect>".format(state.current, i.attrib['kind']))
             else:
                 has_block_elements = True
 
                 # There was a section open, but it differs from this one, close
                 # it
-                if previous_section and previous_section != i.attrib['kind']:
+                if previous_section and ((i.attrib['kind'] != 'par' and previous_section != i.attrib['kind']) or (i.attrib['kind'] == 'par' and i.find('title').text)):
                     out.parsed = out.parsed.rstrip() + '</aside>'
 
                 # Not continuing with a section from before, put a header in
-                if not previous_section or previous_section != i.attrib['kind']:
+                if not previous_section or (i.attrib['kind'] != 'par' and previous_section != i.attrib['kind']) or (i.attrib['kind'] == 'par' and i.find('title').text):
                     if i.attrib['kind'] == 'see':
                         out.parsed += '<aside class="m-note m-default"><h4>See also</h4>'
                     elif i.attrib['kind'] == 'note':
@@ -815,6 +815,30 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET.
                         out.parsed += '<aside class="m-note m-warning"><h4>Attention</h4>'
                     elif i.attrib['kind'] == 'warning':
                         out.parsed += '<aside class="m-note m-danger"><h4>Warning</h4>'
+                    elif i.attrib['kind'] == 'author':
+                        out.parsed += '<aside class="m-note m-default"><h4>Author</h4>'
+                    elif i.attrib['kind'] == 'authors':
+                        out.parsed += '<aside class="m-note m-default"><h4>Authors</h4>'
+                    elif i.attrib['kind'] == 'copyright':
+                        out.parsed += '<aside class="m-note m-default"><h4>Copyright</h4>'
+                    elif i.attrib['kind'] == 'version':
+                        out.parsed += '<aside class="m-note m-default"><h4>Version</h4>'
+                    elif i.attrib['kind'] == 'since':
+                        out.parsed += '<aside class="m-note m-default"><h4>Since</h4>'
+                    elif i.attrib['kind'] == 'date':
+                        out.parsed += '<aside class="m-note m-default"><h4>Date</h4>'
+                    elif i.attrib['kind'] == 'pre':
+                        out.parsed += '<aside class="m-note m-success"><h4>Precondition</h4>'
+                    elif i.attrib['kind'] == 'post':
+                        out.parsed += '<aside class="m-note m-success"><h4>Postcondition</h4>'
+                    elif i.attrib['kind'] == 'invariant':
+                        out.parsed += '<aside class="m-note m-success"><h4>Invariant</h4>'
+                    elif i.attrib['kind'] == 'remark':
+                        out.parsed += '<aside class="m-note m-default"><h4>Remark</h4>'
+                    elif i.attrib['kind'] == 'par':
+                        out.parsed += '<aside class="m-note m-default"><h4>{}</h4>'.format(html.escape(i.findtext('title', '')))
+                    elif i.attrib['kind'] == 'rcs':
+                        out.parsed += '<aside class="m-note m-default"><h4>{}</h4>'.format(html.escape(i.findtext('title', '')))
                     else: # pragma: no cover
                         out.parsed += '<aside class="m-note">'
                         logging.warning("{}: ignoring {} kind of <simplesect>".format(state.current, i.attrib['kind']))

diff --git a/doxygen/test/contents_blocks/index.html b/doxygen/test/contents_blocks/index.html
index 412555031c9376146b5a7083c27a7d6aeaddb4ef..331e8635cbc739060a02814e3c4055e6c335fe10 100644 (file)
--- a/doxygen/test/contents_blocks/index.html
+++ b/doxygen/test/contents_blocks/index.html
@@ -22,7 +22,7 @@
         <h1>
           My Project
         </h1>
-<p>First paragraph containing some content.</p><aside class="m-note m-warning"><h4>Attention</h4><p>An attention section.</p></aside><aside class="m-note m-default"><h4>See also</h4><p>Other section.</p></aside><p>Paragraph following the sections.</p><aside class="m-note m-info"><h4>Note</h4><p>A note.</p></aside><aside class="m-note m-danger"><h4><a href="bug.html#_bug000001" class="m-dox">Bug</a></h4><p>This is a bug.</p></aside><aside class="m-note m-dim"><h4><a href="todo.html#_todo000001" class="m-dox">Todo</a></h4><p>Or a TODO.</p></aside><aside class="m-note m-danger"><h4><a href="deprecated.html#_deprecated000001" class="m-dox">Deprecated</a></h4><p>Which is deprecated.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000001" class="m-dox">Old stuff</a></h4><p>This is old.</p></aside><blockquote><p>A blockquote</p></blockquote><p>Text right after that blockquote should be a new paragraph.</p><ul><li>A simple</li><li>List<ol><li>With one line</li><li>for each</li></ol></li><li>item, so paragraphs are removed</li></ul><ul><li>A simple</li><li>List<ol><li>With the sublist delimited</li><li>by blank lines</li></ol></li><li>should behave the same as above</li></ul><ul><li><p>A new list</p><p>of multiple</p><p>paragraphs.</p></li><li><p>Another item</p><ul><li><p>A sub list</p><p>Another paragraph</p></li></ul></li></ul><p>A paragraph after that list.</p><table class="m-table"><thead><tr><th>Table header</th><th>Another</th><th>Third</th></tr></thead><tbody><tr><td>Cell</td><td>Another cell</td><td>3rd</td></tr><tr><td>Next row</td><td></td><td>This</td></tr><tr><td>is a table</td><td><em>really</em></td><td>yes.</td></tr></tbody></table><table class="m-table"><thead><tr><th>Table</th><th>with</th></tr><tr><th>two</th><th>row</th></tr></thead><tbody><tr><td>table</td><td>header</td></tr></tbody></table><aside class="m-note m-warning"><h4>Attention</h4><p>Attention, first paragraph.</p><p>Attention, second paragraph.</p><p>Attention, third paragraph.</p></aside><aside class="m-note m-info"><h4>Note</h4><p>A note, not merged with the above.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000002" class="m-dox">Old stuff</a></h4><p>This is not merged.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000003" class="m-dox">Old stuff</a></h4><p>With this. Only on the listing page.</p></aside><aside class="m-note m-danger"><h4>Warning</h4><p>Non-text item after a note/whatever should be part of a paragraph:</p></aside><p><em>This is</em> inside a paragraph.</p>
+<p>First paragraph containing some content.</p><aside class="m-note m-warning"><h4>Attention</h4><p>An attention section.</p></aside><aside class="m-note m-default"><h4>See also</h4><p>Other section.</p></aside><p>Paragraph following the sections.</p><aside class="m-note m-info"><h4>Note</h4><p>A note.</p></aside><aside class="m-note m-danger"><h4><a href="bug.html#_bug000001" class="m-dox">Bug</a></h4><p>This is a bug.</p></aside><aside class="m-note m-dim"><h4><a href="todo.html#_todo000001" class="m-dox">Todo</a></h4><p>Or a TODO.</p></aside><aside class="m-note m-danger"><h4><a href="deprecated.html#_deprecated000001" class="m-dox">Deprecated</a></h4><p>Which is deprecated.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000001" class="m-dox">Old stuff</a></h4><p>This is old.</p></aside><blockquote><p>A blockquote</p></blockquote><p>Text right after that blockquote should be a new paragraph.</p><ul><li>A simple</li><li>List<ol><li>With one line</li><li>for each</li></ol></li><li>item, so paragraphs are removed</li></ul><ul><li>A simple</li><li>List<ol><li>With the sublist delimited</li><li>by blank lines</li></ol></li><li>should behave the same as above</li></ul><ul><li><p>A new list</p><p>of multiple</p><p>paragraphs.</p></li><li><p>Another item</p><ul><li><p>A sub list</p><p>Another paragraph</p></li></ul></li></ul><p>A paragraph after that list.</p><table class="m-table"><thead><tr><th>Table header</th><th>Another</th><th>Third</th></tr></thead><tbody><tr><td>Cell</td><td>Another cell</td><td>3rd</td></tr><tr><td>Next row</td><td></td><td>This</td></tr><tr><td>is a table</td><td><em>really</em></td><td>yes.</td></tr></tbody></table><table class="m-table"><thead><tr><th>Table</th><th>with</th></tr><tr><th>two</th><th>row</th></tr></thead><tbody><tr><td>table</td><td>header</td></tr></tbody></table><aside class="m-note m-warning"><h4>Attention</h4><p>Attention, first paragraph.</p><p>Attention, second paragraph.</p><p>Attention, third paragraph.</p></aside><aside class="m-note m-info"><h4>Note</h4><p>A note, not merged with the above.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000002" class="m-dox">Old stuff</a></h4><p>This is not merged.</p></aside><aside class="m-note m-default"><h4><a href="old.html#_old000003" class="m-dox">Old stuff</a></h4><p>With this. Only on the listing page.</p></aside><aside class="m-note m-danger"><h4>Warning</h4><p>Non-text item after a note/whatever should be part of a paragraph:</p></aside><p><em>This is</em> inside a paragraph.</p><aside class="m-note m-default"><h4>Id</h4><p>some strange RCS content</p></aside><aside class="m-note m-default"><h4>Author</h4><p>The Author</p></aside><aside class="m-note m-default"><h4>Authors</h4><p>Another Author, That Intern We Forgot The Name Of</p></aside><aside class="m-note m-default"><h4>Version</h4><p>1.0rc3</p></aside><aside class="m-note m-default"><h4>Since</h4><p>1.0rc1</p></aside><aside class="m-note m-default"><h4>Date</h4><p>2018-02-09</p></aside><aside class="m-note m-success"><h4>Precondition</h4><p>A precondition.</p></aside><aside class="m-note m-success"><h4>Postcondition</h4><p>A postcondition.</p></aside><aside class="m-note m-default"><h4>Copyright</h4><p>This is illegal to use.</p></aside><aside class="m-note m-success"><h4>Invariant</h4><p>Everything is changing all the time.</p></aside><aside class="m-note m-default"><h4>Remark</h4><p>What does a <code>remark</code> mean and how is it different from <code>note</code>, anyway?</p><p>Paragraph that goes to the remark section</p></aside><aside class="m-note m-default"><h4>Paragraph title</h4><p>Paragraph that goes separately</p><p>Paragraph that adds to the previous</p></aside>
       </div>
     </div>
   </div>

diff --git a/doxygen/test/contents_blocks/input.dox b/doxygen/test/contents_blocks/input.dox
index 2ca6bd96c981e6b32254a2a841cf66c9bb4eb9fe..80613a3ebbba40ff41b58084b12ada24fb4974a2 100644 (file)
--- a/doxygen/test/contents_blocks/input.dox
+++ b/doxygen/test/contents_blocks/input.dox
@@ -91,8 +91,28 @@ is a table      | *really*      | yes.
 
 _This is_ inside a paragraph.
 
-$Author: this is ignored $
+$Id: some strange RCS content $
 
+@author The Author
+@authors Another Author, That Intern We Forgot The Name Of
+@version 1.0rc3
+@since 1.0rc1
+@date 2018-02-09
+@pre A precondition.
+@post A postcondition.
+@copyright This is illegal to use.
+@invariant Everything is changing all the time.
+
+@remark What does a `remark` mean and how is it different from `note`, anyway?
+
+@par
+    Paragraph that goes to the remark section
+
+@par Paragraph title
+    Paragraph that goes separately
+
+@par
+    Paragraph that adds to the previous
 */
 
 /** @page other Other page