Skip to contentSkip to conversation

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

PATCH Applied John Snow 2 participants 2 messages Aug 22, 2024 – Aug 27, 2024

lore
Share & tools
lore

John Snow

author
#0 lore raw

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

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" :tm:. I am still in the process of rewriting qapidoc, so I didn't give it much deeper thought.

---
 docs/sphinx/qapidoc.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)
docs/sphinx/qapidoc.py +2 -3
index 738b2450fb1..5f96b46270b 100644
@@ -388,6 +388,7 @@ def _start_new_heading(self, heading, level):
         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 @@ def freeform(self, doc):
             # 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):
Signature · 1 line
2.45.0
Tested-by Acked-by on v1 1/1 Applied
#1 lore raw
Quoted 17 lines · John Snow

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.

Quoted 6 lines

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

Queued, thanks!