mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/sphinx: fix extra stuff in TOC after freeform QMP sections

Browse Source 
Freeform sections with titles are currently generating a TOC entry for
the first paragraph in the section after the header, which is not what
we want.

(Easiest to observe directly in the QMP reference manual's
"Introduction" section.)

When freeform sections are parsed, we create both a section header *and*
an empty, title-less section. This causes some problems with sphinx's
post-parse tree transforms, see also 2664f317 - this is a similar issue:
Sphinx doesn't like section-less titles and it also doesn't like
title-less sections.

Modify qapidoc.py to parse text directly into the preceding section
title as child nodes, eliminating the section duplication. This removes
the extra text from the TOC.

Only very, very lightly tested: "it looks right at a glance" ™️. I am
still in the process of rewriting qapidoc, so I didn't give it much
deeper thought.

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240822204803.1649762-1-jsnow@redhat.com>
This commit is contained in:
John Snow 2024-08-22 16:48:03 -04:00 committed by Markus Armbruster
parent afaee42f77
commit 43e0d14ee0
1 changed files with 2 additions and 3 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
docs/sphinx/qapidoc.py
View File

@ -388,6 +388,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
self._active_headings[level - 1] += snode
self._active_headings = self._active_headings[:level]
self._active_headings.append(snode)
return snode
def _add_node_to_current_heading(self, node):
"""Add the node to whatever the current active heading is"""
@ -417,13 +418,11 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
# the first line of the block)
(heading, _, text) = text.partition('\n')
(leader, _, heading) = heading.partition(' ')
self._start_new_heading(heading, len(leader))
node = self._start_new_heading(heading, len(leader))
if text == '':
return
node = self._make_section(None)
self._parse_text_into_node(text, node)
self._add_node_to_current_heading(node)
self._cur_doc = None
def _parse_text_into_node(self, doctext, node):