Merge tag 'pull-qapi-2025-07-14-v2' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2025-07-14

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmh19QoSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZThVIP/2v9M9C9k7q3bAku38gO6LqU/TJINKEt
# ZlJt7L3LWRC51rpTmhTs6ZchdErs0wnNs2gCH/HjANDofa8lz9u7mpqUo+hVIW2r
# eUi7uEURIBqsfMgantrQu1uhJg3rbtd9gWtxwTJm3qoFKjwxrWlxhEqOFlNSoqkv
# DpoBD6X7zhUtEq6Z5IIsOBI2zqaXNleSsYWdgxJou8cvHMZkgdcvEyE36nRFsl2k
# JSbnRLzFxsxuxd0bIBSrA3+I1pC9pWYS9ZY1qTnyPIX7MxeVvYupaWdOYlpELxi5
# 4zz7stS5wcvUJ+X7+HuobOofBjHljcHVxE06ACr38sQ2Ajqn3jhijQrDrtYdxG5P
# 3kCnP+AY+qFa2CN/Ik7q2be5jz6Ws/3kxZrv/4/LrHa5ez1xB/orooQVZId0eKke
# 5iQOyA9gNXAdJ2JJYdIAZduBg2b8tY892qtMufBA+XDNA3vGek2OixWC0QY5hZKW
# y3AKjVHP/sProyCvbyT7Fta8sIRLcIVD0IHjzr7pLVd/lp/WzKAJpg6y8J2wvn6z
# cnEUC5CceiYa8SbGOVfswR1yy06IIpJkw6cxoCzB3a2blfkvxGv4mCY6QiZh8K3W
# 6xj6u1J539NWRGVkvnQWJ4/7MdFAOEqih4AqRpRLnRXJ+hzDVUkgCeZwtr+v6AVi
# mNVLttTKPpvy
# =2BHn
# -----END PGP SIGNATURE-----
# gpg: Signature made Tue 15 Jul 2025 02:28:26 EDT
# gpg:                using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg:                issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg:                 aka "Markus Armbruster <armbru@pond.sub.org>" [full]
# Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867  4E5F 3870 B400 EB91 8653

* tag 'pull-qapi-2025-07-14-v2' of https://repo.or.cz/qemu/armbru: (29 commits)
  qapi: add cross-references to misc modules
  qapi: add cross-references to yank.json
  qapi: add cross-references to virtio.json
  qapi: add cross-references to ui.json
  qapi: add cross-references to sockets.json
  qapi: add cross-references to run-state.json
  qapi: add cross-references to replay.json
  qapi: add cross-references to QOM
  qapi: add cross-references to pci.json
  qapi: add cross-references to net.json
  qapi: add cross-references to migration.json
  qapi: add cross-references to Machine core
  qapi: add cross-references to job.json
  qapi: add cross-references to dump.json
  qapi: add cross-references to crypto.json
  qapi: add cross-references to block layer
  qapi: add cross-references to authz.json
  qapi: add cross-references to acpi.json
  qapi: rephrase return docs to avoid type name
  qapi: remove trivial "Returns:" sections
  ...

Signed-off-by: Stefan Hajnoczi <stefanha@redhat.com>

1 files changed, 24 insertions, 72 deletions

diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 8011ac9efa..c2f09bac16 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -64,8 +64,6 @@ from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.nodes import nested_parse_with_titles
 
-from qapidoc_legacy import QAPISchemaGenRSTVisitor  # type: ignore
-
 
 if TYPE_CHECKING:
     from typing import (
@@ -218,6 +216,11 @@ class Transmogrifier:
         typ = self.format_type(member)
         self.add_field(kind, member.name, body, info, typ)
 
+    @staticmethod
+    def reformat_arobase(text: str) -> str:
+        """ reformats @var to ``var`` """
+        return re.sub(r"@([\w-]+)", r"``\1``", text)
+
     # Transmogrification helpers
 
     def visit_paragraph(self, section: QAPIDoc.Section) -> None:
@@ -255,22 +258,28 @@ class Transmogrifier:
     def visit_returns(self, section: QAPIDoc.Section) -> None:
         assert isinstance(self.entity, QAPISchemaCommand)
         rtype = self.entity.ret_type
-        # q_empty can produce None, but we won't be documenting anything
-        # without an explicit return statement in the doc block, and we
-        # should not have any such explicit statements when there is no
-        # return value.
+        # return statements will not be present (and won't be
+        # autogenerated) for any command that doesn't return
+        # *something*, so rtype will always be defined here.
         assert rtype
 
         typ = self.format_type(rtype)
         assert typ
-        assert section.text
-        self.add_field("return", typ, section.text, section.info)
+
+        if section.text:
+            self.add_field("return", typ, section.text, section.info)
+        else:
+            self.add_lines(f":return-nodesc: {typ}", section.info)
 
     def visit_errors(self, section: QAPIDoc.Section) -> None:
-        # FIXME: the formatting for errors may be inconsistent and may
-        # or may not require different newline placement to ensure
-        # proper rendering as a nested list.
-        self.add_lines(f":error:\n{section.text}", section.info)
+        # If the section text does not start with a space, it means text
+        # began on the same line as the "Error:" string and we should
+        # not insert a newline in this case.
+        if section.text[0].isspace():
+            text = f":error:\n{section.text}"
+        else:
+            text = f":error: {section.text}"
+        self.add_lines(text, section.info)
 
     def preamble(self, ent: QAPISchemaDefinition) -> None:
         """
@@ -357,8 +366,7 @@ class Transmogrifier:
 
         # Add sections in source order:
         for i, section in enumerate(sections):
-            # @var is translated to ``var``:
-            section.text = re.sub(r"@([\w-]+)", r"``\1``", section.text)
+            section.text = self.reformat_arobase(section.text)
 
             if section.kind == QAPIDoc.Kind.PLAIN:
                 self.visit_paragraph(section)
@@ -393,44 +401,9 @@ class Transmogrifier:
         self.ensure_blank_line()
 
     def visit_freeform(self, doc: QAPIDoc) -> None:
-        # TODO: Once the old qapidoc transformer is deprecated, freeform
-        # sections can be updated to pure rST, and this transformed removed.
-        #
-        # For now, translate our micro-format into rST. Code adapted
-        # from Peter Maydell's freeform().
-
         assert len(doc.all_sections) == 1, doc.all_sections
         body = doc.all_sections[0]
-        text = body.text
-        info = doc.info
-
-        if re.match(r"=+ ", text):
-            # Section/subsection heading (if present, will always be the
-            # first line of the block)
-            (heading, _, text) = text.partition("\n")
-            (leader, _, heading) = heading.partition(" ")
-            # Implicit +1 for heading in the containing .rst doc
-            level = len(leader) + 1
-
-            # https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections
-            markers = ' #*=_^"'
-            overline = level <= 2
-            marker = markers[level]
-
-            self.ensure_blank_line()
-            # This credits all 2 or 3 lines to the single source line.
-            if overline:
-                self.add_line(marker * len(heading), info)
-            self.add_line(heading, info)
-            self.add_line(marker * len(heading), info)
-            self.ensure_blank_line()
-
-            # Eat blank line(s) and advance info
-            trimmed = text.lstrip("\n")
-            text = trimmed
-            info = info.next_line(len(text) - len(trimmed) + 1)
-
-        self.add_lines(text, info)
+        self.add_lines(self.reformat_arobase(body.text), doc.info)
         self.ensure_blank_line()
 
     def visit_entity(self, ent: QAPISchemaDefinition) -> None:
@@ -504,15 +477,9 @@ class QAPIDocDirective(NestedDirective):
     option_spec = {
         "qapifile": directives.unchanged_required,
         "namespace": directives.unchanged,
-        "transmogrify": directives.flag,
     }
     has_content = False
 
-    def new_serialno(self) -> str:
-        """Return a unique new ID string suitable for use as a node's ID"""
-        env = self.state.document.settings.env
-        return "qapidoc-%d" % env.new_serialno("qapidoc")
-
     def transmogrify(self, schema: QAPISchema) -> nodes.Element:
         logger.info("Transmogrifying QAPI to rST ...")
         vis = Transmogrifier()
@@ -590,21 +557,10 @@ class QAPIDocDirective(NestedDirective):
                     outfile.write(f" {rcol}")
                 outfile.write("\n")
 
-    def legacy(self, schema: QAPISchema) -> nodes.Element:
-        vis = QAPISchemaGenRSTVisitor(self)
-        vis.visit_begin(schema)
-        for doc in schema.docs:
-            if doc.symbol:
-                vis.symbol(doc, schema.lookup_entity(doc.symbol))
-            else:
-                vis.freeform(doc)
-        return vis.get_document_node()  # type: ignore
-
     def run(self) -> Sequence[nodes.Node]:
         env = self.state.document.settings.env
         qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
-        transmogrify = "transmogrify" in self.options
 
         try:
             schema = QAPISchema(qapifile)
@@ -617,11 +573,7 @@ class QAPIDocDirective(NestedDirective):
             # so they are displayed nicely to the user
             raise ExtensionError(str(err)) from err
 
-        if transmogrify:
-            contentnode = self.transmogrify(schema)
-        else:
-            contentnode = self.legacy(schema)
-
+        contentnode = self.transmogrify(schema)
         return contentnode.children