From 2664f3176a85aff556e5d82ad4396bda67a20b39 Mon Sep 17 00:00:00 2001 From: John Snow Date: Wed, 26 Jun 2024 18:21:13 -0400 Subject: [PATCH] docs/qapidoc: fix nested parsing under untagged sections 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 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> --- docs/sphinx/qapidoc.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f9683444b1..efcd84656f 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -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 -- 2.49.0