[PULL 0/1] QAPI patches patches for 2024-08-27

[PULL 0/1] QAPI patches patches for 2024-08-27

[Markus Armbruster]

I'm nominating this fix for v9.1 because it can only affect generated
documentation, and CI should protect us from surprise build breaks.
Feel free to delay it to v9.2 if you think even that is too much risk
or simply too much trouble to be worthwhile.

The following changes since commit afaee42f777bc359db95f692804f7fc7e12c0c02:

  Merge tag 'pull-nbd-2024-08-26' of https://repo.or.cz/qemu/ericb into staging (2024-08-27 07:06:42 +1000)

are available in the Git repository at:

  https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-08-27

for you to fetch changes up to 43e0d14ee09a0565adcf4ce5f35be79695958fb0:

  docs/sphinx: fix extra stuff in TOC after freeform QMP sections (2024-08-27 11:10:58 +0200)

----------------------------------------------------------------
QAPI patches patches for 2024-08-27

----------------------------------------------------------------
John Snow (1):
      docs/sphinx: fix extra stuff in TOC after freeform QMP sections

 docs/sphinx/qapidoc.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

-- 
2.46.0

[PULL 1/1] docs/sphinx: fix extra stuff in TOC after freeform QMP sections

[Markus Armbruster]

From: John Snow <jsnow@redhat.com>

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.

Reported-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240822204803.1649762-1-jsnow@redhat.com>
---
 docs/sphinx/qapidoc.py | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 738b2450fb..5f96b46270 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -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):
-- 
2.46.0

Re: [PULL 0/1] QAPI patches patches for 2024-08-27

[Richard Henderson]

On 8/27/24 20:35, Markus Armbruster wrote:
> I'm nominating this fix for v9.1 because it can only affect generated
> documentation, and CI should protect us from surprise build breaks.
> Feel free to delay it to v9.2 if you think even that is too much risk
> or simply too much trouble to be worthwhile.
> 
> The following changes since commit afaee42f777bc359db95f692804f7fc7e12c0c02:
> 
>    Merge tag 'pull-nbd-2024-08-26' of https://repo.or.cz/qemu/ericb into staging (2024-08-27 07:06:42 +1000)
> 
> are available in the Git repository at:
> 
>    https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-08-27
> 
> for you to fetch changes up to 43e0d14ee09a0565adcf4ce5f35be79695958fb0:
> 
>    docs/sphinx: fix extra stuff in TOC after freeform QMP sections (2024-08-27 11:10:58 +0200)
> 
> ----------------------------------------------------------------
> QAPI patches patches for 2024-08-27
> 
> ----------------------------------------------------------------
> John Snow (1):
>        docs/sphinx: fix extra stuff in TOC after freeform QMP sections
> 
>   docs/sphinx/qapidoc.py | 5 ++---
>   1 file changed, 2 insertions(+), 3 deletions(-)
> 

Applied, thanks.  Please update https://wiki.qemu.org/ChangeLog/9.1 as appropriate.

r~