Merge tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru into staging

QAPI patches patches for 2024-07-06

# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaI6xcSHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTTbQP/AonsqGYQyOPCWae9dfDt+Wy+k2gthoB
# dn/3SRjYnA23avEv2/AGAPxgp5MHkpdhh8eqNjWq9QgqgEUh/m0nJztS/MiLMHsR
# /PENPy4V2QFf7s5XtIutLiKXgGbzwtHxrbwnCNyQZW6dAK67VBTq5hPQSxFwBVga
# FDVm+DS2JehJ7IPMVmPT5gjI2cyDYNc/rxbvcbcb5SqirfJdPFk9nMJUrQ0Qubfs
# c9D6l8Cwzbm4JfSeRThs8v9CsDZ1+OIXnpDgGAP9hr7+yYFsovLSHfiLGFxnFXiN
# gSKLBNRIzXnC9cFsKY4jXuqFoSFblRccqCtPSYb7sAp3OVwKq3kA/XNuPIAPii8S
# cm+bhVJ3lyXUW5/6qruS5tOEkpsTnXC45Uw9nvZDEVXANMn3viZ1qInxKak8Nr+p
# k0bOHGE4NzRKkAvGDaTooUOlhG4iy9M+Q4dTcwKIoXTs1Euo8uOjAL+jGwT2pan5
# fb/P1cIqMgMpwSQjwIs7LoYMk20FF44CPtuwA+m85iLbTiiuUfQ4bTnVNMOQMibq
# 3QWIrEDfxwrvwMPsv/u/hcc5d2Tb+5QP9CeVmT9woSXJqU2g4yvKKP9JBf7jUFMC
# fTpNRcHOWsIoz+AgOrUeYe67fLpqUWQii08JhPg5f4ybbEzkzZub0zOKNFLYumG0
# VT3BQlO+8LdW
# =RwDq
# -----END PGP SIGNATURE-----
# gpg: Signature made Fri 05 Jul 2024 11:58:31 PM PDT
# 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]

* tag 'pull-qapi-2024-07-06' of https://repo.or.cz/qemu/armbru:
  sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
  qapi/parser: don't parse rST markup as section headers
  qapi: add markup to note blocks
  qapi: update prose in note blocks
  qapi: convert "Note" sections to plain rST
  qapi: nail down convention that Errors sections are lists
  qapi: fix non-compliant JSON examples
  docs/qapidoc: fix nested parsing under untagged sections
  qapi/parser: fix comment parsing immediately following a doc block
  qapi/parser: preserve indentation in QAPIDoc sections
  docs/qapidoc: delint a tiny portion of the module
  docs/qapidoc: remove unused intersperse function
  qapi: linter fixups

Signed-off-by: Richard Henderson <richard.henderson@linaro.org>

4 files changed, 35 insertions, 14 deletions

diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py
index 86c075a..ac14b20 100644
--- a/scripts/qapi/introspect.py
+++ b/scripts/qapi/introspect.py
@@ -27,8 +27,8 @@ from .gen import QAPISchemaMonolithicCVisitor
 from .schema import (
     QAPISchema,
     QAPISchemaAlternatives,
-    QAPISchemaBranches,
     QAPISchemaArrayType,
+    QAPISchemaBranches,
     QAPISchemaBuiltinType,
     QAPISchemaEntity,
     QAPISchemaEnumMember,
@@ -233,9 +233,9 @@ const QLitObject %(c_name)s = %(c_string)s;
             typ = type_int
         elif (isinstance(typ, QAPISchemaArrayType) and
               typ.element_type.json_type() == 'int'):
-            type_intList = self._schema.lookup_type('intList')
-            assert type_intList
-            typ = type_intList
+            type_intlist = self._schema.lookup_type('intList')
+            assert type_intlist
+            typ = type_intlist
         # Add type to work queue if new
         if typ not in self._used_types:
             self._used_types.append(typ)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 7b13a58..6ad5663 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -448,7 +448,7 @@ class QAPISchemaParser:
         indent = must_match(r'\s*', line).end()
         if not indent:
             return line
-        doc.append_line(line[indent:])
+        doc.append_line(line)
         prev_line_blank = False
         while True:
             self.accept(False)
@@ -465,7 +465,7 @@ class QAPISchemaParser:
                     self,
                     "unexpected de-indent (expected at least %d spaces)" %
                     indent)
-            doc.append_line(line[indent:])
+            doc.append_line(line)
             prev_line_blank = True
 
     def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]:
@@ -544,9 +544,29 @@ class QAPISchemaParser:
                         line = self.get_doc_indented(doc)
                     no_more_args = True
                 elif match := re.match(
-                        r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
-                        line):
+                        r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
+                        r'(?!::): *',
+                        line,
+                ):
                     # tagged section
+
+                    # Note: "sections" with two colons are left alone as
+                    # rST markup and not interpreted as a section heading.
+
+                    # TODO: Remove this error sometime in 2025 or so
+                    # after we've fully transitioned to the new qapidoc
+                    # generator.
+
+                    # See commit message for more markup suggestions O:-)
+                    if 'Note' in match.group(1):
+                        emsg = (
+                            f"The '{match.group(1)}' section is no longer "
+                            "supported. Please use rST's '.. note::' or "
+                            "'.. admonition:: notes' directives, or another "
+                            "suitable admonition instead."
+                        )
+                        raise QAPIParseError(self, emsg)
+
                     doc.new_tagged_section(self.info, match.group(1))
                     text = line[match.end():]
                     if text:
@@ -583,7 +603,7 @@ class QAPISchemaParser:
                 line = self.get_doc_line()
                 first = False
 
-        self.accept(False)
+        self.accept()
         doc.end()
         return doc
 
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 721c470..d65c35f 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -730,6 +730,7 @@ class QAPISchemaVariants:
         for v in self.variants:
             v.set_defined_in(name)
 
+    # pylint: disable=unused-argument
     def check(
             self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
     ) -> None:
@@ -1166,7 +1167,7 @@ class QAPISchema:
                 defn.info, "%s is already defined" % other_defn.describe())
         self._entity_dict[defn.name] = defn
 
-    def lookup_entity(self,name: str) -> Optional[QAPISchemaEntity]:
+    def lookup_entity(self, name: str) -> Optional[QAPISchemaEntity]:
         return self._entity_dict.get(name)
 
     def lookup_type(self, name: str) -> Optional[QAPISchemaType]:
@@ -1302,11 +1303,10 @@ class QAPISchema:
         name = 'q_obj_%s-%s' % (name, role)
         typ = self.lookup_entity(name)
         if typ:
-            assert(isinstance(typ, QAPISchemaObjectType))
+            assert isinstance(typ, QAPISchemaObjectType)
             # The implicit object type has multiple users.  This can
             # only be a duplicate definition, which will be flagged
             # later.
-            pass
         else:
             self._def_definition(QAPISchemaObjectType(
                 name, info, None, ifcond, None, None, members, None))
diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py
index e766aca..12f92e4 100644
--- a/scripts/qapi/visit.py
+++ b/scripts/qapi/visit.py
@@ -280,8 +280,9 @@ bool visit_type_%(c_name)s(Visitor *v, const char *name,
         abort();
     default:
         assert(visit_is_input(v));
-        error_setg(errp, "Invalid parameter type for '%%s', expected: %(name)s",
-                         name ? name : "null");
+        error_setg(errp,
+                   "Invalid parameter type for '%%s', expected: %(name)s",
+                   name ? name : "null");
         /* Avoid passing invalid *obj to qapi_free_%(c_name)s() */
         g_free(*obj);
         *obj = NULL;