mirrors/qemu
0
0
Fork 0
mirror of https://github.com/qemu/qemu.git synced 2024-11-30 23:33:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs/qapidoc: fix nested parsing under untagged sections

Browse Source 
Sphinx does not like sections without titles, because it wants to
convert every section into a reference. When there is no title, it
struggles to do this and transforms the tree inproperly.

Depending on the rST used, this may result in an assertion error deep in
the docutils HTMLWriter.

(Observed when using ".. admonition:: Notes" under such a section - When
this is transformed with its own <title> element, Sphinx is fooled into
believing this title belongs to the section and incorrect mutates the
docutils tree, leading to errors during rendering time.)

When parsing an untagged section (free paragraphs), skip making a hollow
section and instead append the parse results to the prior section.

Many Bothans died to bring us this information.

The resulting output changes are basically invisible.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-8-jsnow@redhat.com>
[Mention output changes in commit message]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2024-06-26 18:21:13 -04:00 committed by Markus Armbruster
parent 83deda8769
commit 2664f3176a
1 changed files with 11 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

16
docs/sphinx/qapidoc.py
View File

@ -272,14 +272,20 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
if section.tag and section.tag == 'TODO':
# Hide TODO: sections
continue
if not section.tag:
# Sphinx cannot handle sectionless titles;
# Instead, just append the results to the prior section.
container = nodes.container()
self._parse_text_into_node(section.text, container)
nodelist += container.children
continue
snode = self._make_section(section.tag)
if section.tag and section.tag.startswith('Example'):
if section.tag.startswith('Example'):
snode += self._nodes_for_example(dedent(section.text))
else:
self._parse_text_into_node(
dedent(section.text) if section.tag else section.text,
snode,
)
self._parse_text_into_node(dedent(section.text), snode)
nodelist.append(snode)
return nodelist