From: Vladimír Vondruš Date: Wed, 6 Dec 2017 21:48:37 +0000 (+0100) Subject: doxygen: table parsing. X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~cjwatson/git?a=commitdiff_plain;h=acec05886fc16a0033a8c6cf013d3c5c3f6534c1;p=blog.git doxygen: table parsing. --- diff --git a/doc/doxygen.rst b/doc/doxygen.rst index f2379c1a..0696f9e7 100644 --- a/doc/doxygen.rst +++ b/doc/doxygen.rst @@ -306,13 +306,13 @@ modifications: added after ``::`` and ``_`` in long symbols in link titles and after ``/`` in URLs. -Single-paragraph list items, function parameter description and return value -documentation is stripped from the enclosing :html:`

` tag to make the output -more compact. If multiple paragraphs are present, nothing is stripped. In case -of lists, they are then rendered in an inflated form. However, in order to -achieve even spacing also with single-paragraph items, it's needed use some -explicit markup. Adding :html:`

` to a single-paragraph item will make -sure the enclosing :html:`

` is not stripped. +Single-paragraph list items, function parameter description, table cell content +and return value documentation is stripped from the enclosing :html:`

` tag +to make the output more compact. If multiple paragraphs are present, nothing is +stripped. In case of lists, they are then rendered in an inflated form. +However, in order to achieve even spacing also with single-paragraph items, +it's needed use some explicit markup. Adding :html:`

` to a +single-paragraph item will make sure the enclosing :html:`

` is not stripped. .. code-figure:: diff --git a/doxygen/dox2html5.py b/doxygen/dox2html5.py index 28c66b0b..6f594258 100755 --- a/doxygen/dox2html5.py +++ b/doxygen/dox2html5.py @@ -180,7 +180,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # - and # - # - , , - # - + # - , # - block # - (complex block/inline autodetection involved, so # the check is deferred to later in the loop) @@ -198,7 +198,7 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. # I.e., not wrapping "A paragraph" in a

, but only if it's # immediately followed by another and it's the first paragraph in a # list item. We check that using the immediate_parent variable. - if (i.tag in ['heading', 'blockquote', 'xrefsect', 'variablelist', 'verbatim', 'itemizedlist', 'orderedlist', 'image'] or (i.tag == 'simplesect' and i.attrib['kind'] != 'return') or (i.tag == 'formula' and i.text.startswith('\[ ') and i.text.endswith(' \]'))) and element.tag == 'para' and out.write_paragraph_close_tag: + if (i.tag in ['heading', 'blockquote', 'xrefsect', 'variablelist', 'verbatim', 'itemizedlist', 'orderedlist', 'image', 'table'] or (i.tag == 'simplesect' and i.attrib['kind'] != 'return') or (i.tag == 'formula' and i.text.startswith('\[ ') and i.text.endswith(' \]'))) and element.tag == 'para' and out.write_paragraph_close_tag: out.is_reasonable_paragraph = False out.parsed = out.parsed.rstrip() if not out.parsed: @@ -311,6 +311,31 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.parsed += '

  • {}
    • '.format(parse_desc(state, li)) out.parsed += ''.format(tag) + elif i.tag == 'table': + has_block_elements = True + out.parsed += '
    ' + inside_tbody = False + + row: ET.Element + for row in i: + assert row.tag == 'row' + is_header_row = True + row_data = '' + for entry in row: + assert entry.tag == 'entry' + is_header = entry.attrib['thead'] == 'yes' + is_header_row = is_header_row and is_header + row_data += '<{0}>{1}'.format('th' if is_header else 'td', parse_desc(state, entry)) + if is_header_row: + assert not inside_tbody # Assume there's only one header row + out.parsed += '{}'.format(row_data) + inside_tbody = True + else: + out.parsed += '{}'.format(row_data) + + if inside_tbody: out.parsed += '' + out.parsed += '
    ' + elif i.tag == 'simplesect': # Return value is separated from the text flow if i.attrib['kind'] == 'return': @@ -601,8 +626,9 @@ def parse_desc_internal(state: State, element: ET.Element, immediate_parent: ET. out.parsed = out.parsed[3:-4] # Strip superfluous

    for simple elments (list items, parameter and - # return value description), but only if there is just a single paragraph - elif (element.tag in ['listitem', 'parameterdescription'] or (element.tag == 'simplesect' and element.attrib['kind'] == 'return')) and not has_block_elements and paragraph_count == 1: + # return value description, table cells), but only if there is just a + # single paragraph + elif (element.tag in ['listitem', 'parameterdescription', 'entry'] or (element.tag == 'simplesect' and element.attrib['kind'] == 'return')) and not has_block_elements and paragraph_count == 1: assert out.parsed.startswith('

    ') and out.parsed.endswith('

    ') out.parsed = out.parsed[3:-4] diff --git a/doxygen/test/contents_blocks/index.html b/doxygen/test/contents_blocks/index.html index 262d6265..2cb7ea84 100644 --- a/doxygen/test/contents_blocks/index.html +++ b/doxygen/test/contents_blocks/index.html @@ -39,7 +39,7 @@

    First paragraph containing some content.

    Paragraph following the sections.

    -

    A blockquote

    Text right after that blockquote should be a new paragraph.

    A paragraph after that list.

    +

    A blockquote

    Text right after that blockquote should be a new paragraph.

    A paragraph after that list.

    Table headerAnotherThird
    CellAnother cell3rd
    Next rowYupThis
    is a tablereallyyes.
    diff --git a/doxygen/test/contents_blocks/input.dox b/doxygen/test/contents_blocks/input.dox index 04902caf..604d7ff2 100644 --- a/doxygen/test/contents_blocks/input.dox +++ b/doxygen/test/contents_blocks/input.dox @@ -53,6 +53,12 @@ Text right after that blockquote should be a new paragraph. A paragraph after that list. +Table header | Another | Third +--------------- | ------------- | ----- +Cell | Another cell | 3rd +Next row | Yup | This +is a table | *really* | yes. + */ /** @page other Other page