From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490806; cv=none; d=zohomail.com; s=zohoarc; b=TW1KsGI4qEh77LG3sHuySPg/agV3x0PUzP7R3cBkC1mxsiQobbKLNouLJyXljRU35Q9XBc2QVQBwU3mdSwvkX225PpQ10w6OX4dfv10u3J10Zk37VKS+BKMPX6kN6gH/1mqzVzjqWOXoH5aCHYtr3+gAFGTiIxGczPaCFYRfA/E= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490806; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=u0MZS1bSbu4EQv/u0Yr8n1ph2IX/3wmcQ+CPEwREwE4=; b=JCPps1Btf4tWmfp4q/tUpJzIIXfUHaBS+WQ4QzqUxQYlzeSJzl6BItTLvnSpoS4KD+0UVln9EyaIp8PqszUpYJEXZxePmVSvK8tSE4ZMi3syQhEDL8s+5p6LuzVizbDYjB7dsHmL0fj/ZB+h0UgoOT2bdpmKjvV7ea5ar4JLRBM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17774908060731023.2921153770623; Wed, 29 Apr 2026 12:26:46 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAYL-0006LV-In; Wed, 29 Apr 2026 15:26:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYH-0006JP-Vv for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:30 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYG-0007jY-0n for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:29 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-393-s-oFL-bnO269XFOLdvC4lQ-1; Wed, 29 Apr 2026 15:26:23 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D204618003FC; Wed, 29 Apr 2026 19:26:21 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 31716180045E; Wed, 29 Apr 2026 19:26:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490786; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=u0MZS1bSbu4EQv/u0Yr8n1ph2IX/3wmcQ+CPEwREwE4=; b=gT+n+3mXZ3aBN289ui8TKBLlUpjWgNwOUg8xPgAT5D9IyleTNJYOh4aDU1LBAXV0S0kE+9 dH5w5m5RjIUOsUISLg2/nj49f3MChElxMExkyCtOueHzYOKyTeC1i9jN3FfF90NEfppsNO Nr8BawNEa/6FvNtUSh6n0BzD6zA574U= X-MC-Unique: s-oFL-bnO269XFOLdvC4lQ-1 X-Mimecast-MFC-AGG-ID: s-oFL-bnO269XFOLdvC4lQ_1777490782 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 01/13] tests/qapi: generate output in source order Date: Wed, 29 Apr 2026 15:25:59 -0400 Message-ID: <20260429192611.1581223-2-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490808785154100 Content-Type: text/plain; charset="utf-8" Rewrite the test doc generator to produce output in source order instead of arbitrarily by section name. This patch removes our last use of the "body" field, which has an effect on how the first plaintext section of each test documented is printed: we now print "section=3DPlain" followed by the section text instead of "body=3D[...]". This patch is motivated by a desire to move the QAPIDoc API away from named fields for specific sections in a bid to force all users to simply iterate through all_sections in order, instead - and to remove the named subsections. Signed-off-by: John Snow --- tests/qapi-schema/doc-good.out | 26 +++++++++++++------------- tests/qapi-schema/test-qapi.py | 15 ++++++++------- 2 files changed, 21 insertions(+), 20 deletions(-) diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 04a55072646..e2be6f96bbf 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -54,15 +54,15 @@ event EVT_BOXED Object boxed=3DTrue feature feat3 doc freeform - body=3D + section=3DPlain ******* Section ******* doc freeform - body=3D + section=3DPlain Just text, no heading. doc freeform - body=3D + section=3DPlain Subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -106,7 +106,7 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum - body=3D + section=3DPlain =20 arg=3Done The _one_ {and only}, description on the same line @@ -119,13 +119,13 @@ a member feature section=3DPlain @two is undocumented doc symbol=3DBase - body=3D + section=3DPlain =20 arg=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 - body=3D + section=3DPlain A paragraph =20 Another paragraph @@ -138,15 +138,15 @@ a feature feature=3Dmember-feat a member feature doc symbol=3DVariant2 - body=3D + section=3DPlain =20 doc symbol=3DObject - body=3D + section=3DPlain =20 feature=3Dunion-feat1 a feature doc symbol=3DAlternate - body=3D + section=3DPlain =20 arg=3Di description starts on the same line @@ -157,11 +157,11 @@ description starts on the same line feature=3Dalt-feat a feature doc freeform - body=3D + section=3DPlain Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd - body=3D + section=3DPlain =20 arg=3Darg1 description starts on a new line, @@ -210,7 +210,7 @@ Note:: section=3DSince 2.10 doc symbol=3Dcmd-boxed - body=3D + section=3DPlain If you're bored enough to read this, go see a video of boxed cats feature=3Dcmd-feat1 a feature @@ -223,7 +223,7 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED - body=3D + section=3DPlain =20 feature=3Dfeat3 a feature diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index cf7fb8a6df5..27885147b4d 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -19,6 +19,7 @@ from io import StringIO =20 from qapi.error import QAPIError +from qapi.parser import QAPIDoc from qapi.schema import QAPISchema, QAPISchemaVisitor =20 =20 @@ -116,13 +117,13 @@ def test_frontend(fname): print('doc symbol=3D%s' % doc.symbol) else: print('doc freeform') - print(' body=3D\n%s' % doc.body.text) - for arg, section in doc.args.items(): - print(' arg=3D%s\n%s' % (arg, section.text)) - for feat, section in doc.features.items(): - print(' feature=3D%s\n%s' % (feat, section.text)) - for section in doc.sections: - print(' section=3D%s\n%s' % (section.kind, section.text)) + for section in doc.all_sections: + if section.kind =3D=3D QAPIDoc.Kind.MEMBER: + print(' arg=3D%s\n%s' % (section.name, section.text)) + elif section.kind =3D=3D QAPIDoc.Kind.FEATURE: + print(' feature=3D%s\n%s' % (section.name, section.text= )) + else: + print(' section=3D%s\n%s' % (section.kind, section.text= )) =20 =20 def open_test_result(dir_name, file_name, update): --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490835; cv=none; d=zohomail.com; s=zohoarc; b=ixexqnrPTAMCCKNgH2frC+93+XIR7spsqMwJlPbpALnqewmN3ch82MwEZC583M2PivdvG4BJ8vuxWU+ds2crOQE4pruRe0PiTEFshfMRK15PXSXn+5u8NExIA3Ot7kaU8Xc4MwtaBn0AtnxTTH+JkHdnrQak8bCKDSBqqNtYw1g= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490835; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=5SsBbo04Cf3PHhAk+89piq6ruPRBLk/9JsjVA6uMw2U=; b=QfrQJH0AeZPa1jM2inwnF8GhDJncRQDrVnMuH/3ObrZz9deC41LtXdPerbmnlxGNpN7LDsWTdVDCxpDNKGrA9/PXhGWKW8pk6JISesMgAoPd2arTH/Pqkib89I4P47RhR8VTGU35vtJccfMmj3PIcDwmjmA20UcLYtu6AyBChqs= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490835854651.1920536615879; Wed, 29 Apr 2026 12:27:15 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAYP-0006Py-E7; Wed, 29 Apr 2026 15:26:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYL-0006My-Ts for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:34 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYK-0007nV-6w for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:33 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-315-mvVghRZWM9ymgvrqCuyPRA-1; Wed, 29 Apr 2026 15:26:27 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2AC4D195608E; Wed, 29 Apr 2026 19:26:26 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 69E7B180045E; Wed, 29 Apr 2026 19:26:22 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490791; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5SsBbo04Cf3PHhAk+89piq6ruPRBLk/9JsjVA6uMw2U=; b=Q/iQL6ubhQ6Q0cbPVr+cJuuKNK8JRwnLYR7OuDjl0BwESQOHQIOGsiUtoa/uOrcuA1N5WI fst4gYlU66s2rhMYgSaphT/WgQwAEFw0yyhy7x570q8P0btl3g0abgNCtyze1fZk/6G/b7 ELbDPgAEG4ANqBj6e0KZL5QSQAT0jxA= X-MC-Unique: mvVghRZWM9ymgvrqCuyPRA-1 X-Mimecast-MFC-AGG-ID: mvVghRZWM9ymgvrqCuyPRA_1777490786 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 02/13] qapi/docs: remove unused QAPIDoc subsection members Date: Wed, 29 Apr 2026 15:26:00 -0400 Message-ID: <20260429192611.1581223-3-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490837065154100 Content-Type: text/plain; charset="utf-8" All users of the QAPIDoc object should be iterating over all_sections and not grabbing arbitrary subsections, if possible. Remove the 'body' and 'sections' members, as they are no longer used. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- scripts/qapi/parser.py | 6 ------ 1 file changed, 6 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c3cf33904ef..b33edbba74f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -732,8 +732,6 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): self.all_sections: List[QAPIDoc.Section] =3D [ QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) ] - # the body section - self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] # dicts mapping parameter/feature names to their description self.args: Dict[str, QAPIDoc.ArgSection] =3D {} self.features: Dict[str, QAPIDoc.ArgSection] =3D {} @@ -742,8 +740,6 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): self.errors: Optional[QAPIDoc.Section] =3D None # "Since" section self.since: Optional[QAPIDoc.Section] =3D None - # sections other than .body, .args, .features - self.sections: List[QAPIDoc.Section] =3D [] =20 def end(self) -> None: for section in self.all_sections: @@ -766,7 +762,6 @@ def ensure_untagged_section(self, info: QAPISourceInfo)= -> None: =20 # start new section section =3D self.Section(info, kind) - self.sections.append(section) self.all_sections.append(section) =20 def new_tagged_section( @@ -790,7 +785,6 @@ def new_tagged_section( raise QAPISemError( info, "duplicated '%s' section" % kind) self.since =3D section - self.sections.append(section) self.all_sections.append(section) =20 def _new_description( --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490813; cv=none; d=zohomail.com; s=zohoarc; b=eCGImkshz0hNr0rBtoAYGoyS22GNBGy783//JoLCNLE9HFFNSvspQgKiu3mqiGXBKP5UPkf0UPlNDH+NqDaJEogJy952vg1xMerq1hQObKFl+2EOPYauZGSAQ3YpJW9SzPY3U9odRdOcfu02+N4EZYUyO7g+ibRhp/wnLF5SvUQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490813; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=r3bFlvRyNHuo5LAmox46R5ptUST3XkFKOLqwa+xbG2U=; b=XksQMqzL0M3s/9NBfk28VX1f0qZOgJQDPmGkXiZqxmDdh70evJw/vYtvHGJ9uHrI2BHGYspqm2EbFZi2Lhf6PHIfTo5/7EK0w4YrnoTaBnE3ArxSEugSSVcrs/7MGcU4q30BndqHSS56SK392fOt3g+LcP7z1Ls6h39+b+teU4s= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490813695382.6939980851199; Wed, 29 Apr 2026 12:26:53 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAYS-0006RR-UM; Wed, 29 Apr 2026 15:26:40 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYQ-0006R3-HI for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:38 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYO-0007qs-BY for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:38 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-338-NVrDnU5xPNK-mbGhr7cGVQ-1; Wed, 29 Apr 2026 15:26:31 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 512D91800350; Wed, 29 Apr 2026 19:26:30 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 63C511800446; Wed, 29 Apr 2026 19:26:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490795; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=r3bFlvRyNHuo5LAmox46R5ptUST3XkFKOLqwa+xbG2U=; b=foWJcgRXKGpr9m9CMd5cutlE6O7Ku2j/cLRJr5zGGsCdpqxACP1S+TU8FO8JWApWssnSid fi+dgYNu8Y3RRdAtVL9e/rWUap3ItRzcYNyqjF5nDrG/7VAzEsBOv3i4zE8CPrZo3Zhz5N o7pbLGCoCHUl/toFOBDgoARNJFOBVuQ= X-MC-Unique: NVrDnU5xPNK-mbGhr7cGVQ-1 X-Mimecast-MFC-AGG-ID: NVrDnU5xPNK-mbGhr7cGVQ_1777490790 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 03/13] qapi/docs: make remaining subsection members "private" Date: Wed, 29 Apr 2026 15:26:01 -0400 Message-ID: <20260429192611.1581223-4-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490815721158500 Content-Type: text/plain; charset="utf-8" These fields are used to provide error checking and internal logistics and should not be used by a user of the library to directly access documentation sections, so make them private. The "since" field alone is left public, as the qapidoc generator does use this field to pull that section out of the regular flow of the document. Signed-off-by: John Snow --- scripts/qapi/parser.py | 54 +++++++++++++++++++++++------------------- 1 file changed, 29 insertions(+), 25 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b33edbba74f..da4756a7424 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -555,7 +555,7 @@ def get_doc(self) -> 'QAPIDoc': break # Non-blank line, first of a section if line =3D=3D 'Features:': - if doc.features: + if doc.has_features: raise QAPIParseError( self, "duplicated 'Features:' line") self.accept(False) @@ -570,7 +570,7 @@ def get_doc(self) -> 'QAPIDoc': if text: doc.append_line(text) line =3D self.get_doc_indented(doc) - if not doc.features: + if not doc.has_features: raise QAPIParseError( self, 'feature descriptions expected') no_more_args =3D True @@ -733,14 +733,18 @@ def __init__(self, info: QAPISourceInfo, symbol: Opti= onal[str] =3D None): QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) ] # dicts mapping parameter/feature names to their description - self.args: Dict[str, QAPIDoc.ArgSection] =3D {} - self.features: Dict[str, QAPIDoc.ArgSection] =3D {} + self._args: Dict[str, QAPIDoc.ArgSection] =3D {} + self._features: Dict[str, QAPIDoc.ArgSection] =3D {} # a command's "Returns" and "Errors" section - self.returns: Optional[QAPIDoc.Section] =3D None - self.errors: Optional[QAPIDoc.Section] =3D None + self._returns: Optional[QAPIDoc.Section] =3D None + self._errors: Optional[QAPIDoc.Section] =3D None # "Since" section self.since: Optional[QAPIDoc.Section] =3D None =20 + @property + def has_features(self) -> bool: + return bool(self._features) + def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') @@ -771,15 +775,15 @@ def new_tagged_section( ) -> None: section =3D self.Section(info, kind) if kind =3D=3D QAPIDoc.Kind.RETURNS: - if self.returns: + if self._returns: raise QAPISemError( info, "duplicated '%s' section" % kind) - self.returns =3D section + self._returns =3D section elif kind =3D=3D QAPIDoc.Kind.ERRORS: - if self.errors: + if self._errors: raise QAPISemError( info, "duplicated '%s' section" % kind) - self.errors =3D section + self._errors =3D section elif kind =3D=3D QAPIDoc.Kind.SINCE: if self.since: raise QAPISemError( @@ -803,16 +807,16 @@ def _new_description( desc[name] =3D section =20 def new_argument(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, QAPIDoc.Kind.MEMBER, self.args) + self._new_description(info, name, QAPIDoc.Kind.MEMBER, self._args) =20 def new_feature(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, QAPIDoc.Kind.FEATURE, self.featu= res) + self._new_description(info, name, QAPIDoc.Kind.FEATURE, self._feat= ures) =20 def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) =20 def connect_member(self, member: 'QAPISchemaMember') -> None: - if member.name not in self.args: + if member.name not in self._args: assert member.info if self.symbol not in member.info.pragma.documentation_excepti= ons: raise QAPISemError(member.info, @@ -823,7 +827,7 @@ def connect_member(self, member: 'QAPISchemaMember') ->= None: =20 section =3D QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) - self.args[member.name] =3D section + self._args[member.name] =3D section =20 # Determine where to insert stub doc - it should go at the # end of the members section(s), if any. Note that index 0 @@ -835,14 +839,14 @@ def connect_member(self, member: 'QAPISchemaMember') = -> None: index +=3D 1 self.all_sections.insert(index, section) =20 - self.args[member.name].connect(member) + self._args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: - if feature.name not in self.features: + if feature.name not in self._features: raise QAPISemError(feature.info, "feature '%s' lacks documentation" % feature.name) - self.features[feature.name].connect(feature) + self._features[feature.name].connect(feature) =20 def ensure_returns(self, info: QAPISourceInfo) -> None: =20 @@ -883,18 +887,18 @@ def _insert_near_kind( =20 def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: - if self.returns and 'returns' not in expr: + if self._returns and 'returns' not in expr: raise QAPISemError( - self.returns.info, + self._returns.info, "'Returns' section, but command doesn't return anythin= g") else: - if self.returns: + if self._returns: raise QAPISemError( - self.returns.info, + self._returns.info, "'Returns' section is only valid for commands") - if self.errors: + if self._errors: raise QAPISemError( - self.errors.info, + self._errors.info, "'Errors' section is only valid for commands") =20 def check(self) -> None: @@ -914,5 +918,5 @@ def check_args_section( "do" if len(bogus) > 1 else "does" )) =20 - check_args_section(self.args, 'member') - check_args_section(self.features, 'feature') + check_args_section(self._args, 'member') + check_args_section(self._features, 'feature') --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490835; cv=none; d=zohomail.com; s=zohoarc; b=ffTtiXrgtIkNIzF/sXt5gk/kNlDuD8mqjrmqjPouNtGTyTe4IKPc0+O/ZmSj5LW8OP6Hm9G6QeKLIN/23jzDB0T4+w9WRYy34DTyyulL4VaT88BkDNl5Hm0RbBt0yPN4I2HrxpFd3ZdG0w3NayBjAldoOp5LM+wIU3Trq02Ega4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490835; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=8JdizDGNlwS8SfnCL8Rcl1SME6qSupIqrJsOC/xLrAc=; b=DgKaDP8EYOUIaZ+hySw6aofmMq3ErCh9v63n2MtvRbr/RDfv95o6nmnXrjDSRR2xopI0HHfu0zbjgTSDmd7Ga0IFOUJ+/308rKtQm9KP+wCsZ8ESZ6q3GdMuzpp1uW9XU+sgtVNrLMtOxcx6z+P0iFO13PI4DgC7rqlLqWDViCE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490835943629.0613037068149; Wed, 29 Apr 2026 12:27:15 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAYf-0006U1-Uq; Wed, 29 Apr 2026 15:26:54 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYV-0006Rj-7p for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYT-0007rU-HY for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:42 -0400 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-582-skGbC1W9NY-NzQKiZfze3g-1; Wed, 29 Apr 2026 15:26:37 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id EC49219560BB; Wed, 29 Apr 2026 19:26:35 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 962DA180045E; Wed, 29 Apr 2026 19:26:30 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490801; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=8JdizDGNlwS8SfnCL8Rcl1SME6qSupIqrJsOC/xLrAc=; b=gNsw6f4p/0b7ewxbrYhMad3HosBUczYk+t2o8bb+xKGjkWXMZ01HoXLadZbSyWPnMZacVo wyAskjqbud+W9e9hg5tv1cfQmkbFAidtXEUnr3KTn6gksf3UAtL4Jfu5Vv/cfL8zvL/HoT gMkZWVfiSi6pjxoSKZfrErPfqShJqgw= X-MC-Unique: skGbC1W9NY-NzQKiZfze3g-1 X-Mimecast-MFC-AGG-ID: skGbC1W9NY-NzQKiZfze3g_1777490796 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 04/13] qapi/docs: add "Intro" section Date: Wed, 29 Apr 2026 15:26:02 -0400 Message-ID: <20260429192611.1581223-5-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490837082154100 Content-Type: text/plain; charset="utf-8" This patch adds an "Intro" doc section, intended to eventually replace the "Plain" doc section alongside a forthcoming "Details" section. For now, this section is not actually instantiated or used, but subsequent patches will slowly convert the leading introductory sections of QAPIDoc documentation to use the new Intro section. A main motivation of this series of changes is to more explicitly delineate the "Introductory" documentation for each QAPI definition for the sake of the inliner. When inlining members, examples, and details from multiple QAPIDoc sections, we will want to omit the "Introductory" text from inlined definitions while keeping notes, caution boxes, examples, and so on. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 5 +++-- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index c2f09bac16c..1f7c15b7075 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> = None: for i, section in enumerate(sections): section.text =3D self.reformat_arobase(section.text) =20 - if section.kind =3D=3D QAPIDoc.Kind.PLAIN: + if section.kind.name in ("PLAIN", "INTRO"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index da4756a7424..97e7dacb0fd 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -631,7 +631,7 @@ def get_doc(self) -> 'QAPIDoc': line =3D self.get_doc_indented(doc) no_more_args =3D True else: - # plain paragraph + # plain paragraph(s) doc.ensure_untagged_section(self.info) doc.append_line(line) line =3D self.get_doc_paragraph(doc) @@ -681,6 +681,7 @@ class Kind(enum.Enum): ERRORS =3D 4 SINCE =3D 5 TODO =3D 6 + INTRO =3D 7 =20 @staticmethod def from_string(kind: str) -> 'QAPIDoc.Kind': @@ -748,7 +749,7 @@ def has_features(self) -> bool: def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') - if section.kind !=3D QAPIDoc.Kind.PLAIN and section.text =3D= =3D '': + if not (section.kind.name in ("INTRO", "PLAIN") or section.tex= t): raise QAPISemError( section.info, "text required after '%s:'" % section.ki= nd) =20 --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490931; cv=none; d=zohomail.com; s=zohoarc; b=XyQL9BhvS7CaLrNZ4v04juuXr/MUyqkRo/3FCgM19Vr76Mja6y5FVeGxW40gH8ymQ3xPztLAPneqZFh3wbsZvLnzPXxsn7kPeINwQ2sdgm0tVj7RG9hxELM8GV+IeGEvIDE4itT/+pQuEsy5AbQrBijB6ZPzwSNzDpEk+X5Q4Ks= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490931; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=R6KxGZvJ/nle8ZjgDAoRf5v3codJAXqzHMYcdxnKGaY=; b=Qf0YKn1fgfhX9g2taesuqilRID7Q/xrHeVUEr4CUqb8HjsRnYGIYRAlVoThQuri7xYOXo0wu59EENGbizOa1Oi1Z+Wxewb3Lm+SlPsBkjutN1F6GSc4QoBMIVjrAVe5zWLuvn0ot0mPyzHm52XnNbGYC35H+DizVOeW0/86KjtU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490931615109.81619658917202; Wed, 29 Apr 2026 12:28:51 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAYr-0006hg-EF; Wed, 29 Apr 2026 15:27:06 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYi-0006bv-TP for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:57 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYg-0007ru-Do for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:56 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-161-OsAr4w-AOcePxqkRthDz4Q-1; Wed, 29 Apr 2026 15:26:41 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 74F38180034C; Wed, 29 Apr 2026 19:26:39 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 313251800446; Wed, 29 Apr 2026 19:26:36 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490804; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=R6KxGZvJ/nle8ZjgDAoRf5v3codJAXqzHMYcdxnKGaY=; b=W/d/OUz2Gk+38qgxAJwm2LrwnJsy8fnhjEJgwuMMi7x8wb5nMEyfsp/jw9FCuGnPIiC9mC e8kagJyoahU74JHBdN2OgPoDutHDsXccNH7ueWRxt+fADXMLOK6MhUCG4WdeopjQEqZ6vk H7knFpcrZWzrpU8ZyOlkA62PDrcBo9U= X-MC-Unique: OsAr4w-AOcePxqkRthDz4Q-1 X-Mimecast-MFC-AGG-ID: OsAr4w-AOcePxqkRthDz4Q_1777490799 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 05/13] qapi/docs: adjust stub member insertion algorithm Date: Wed, 29 Apr 2026 15:26:03 -0400 Message-ID: <20260429192611.1581223-6-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490934497154100 Content-Type: text/plain; charset="utf-8" A forthcoming patch removes the implicit PLAIN section that always starts a QAPIDoc section list. Further future changes begin converting "PLAIN" sections to "INTRO" sections. To accommodate this, the insertion algorithm that places stub and dummy members must be adjusted to cope. This algorithm can handle zero-or-more PLAIN *or* INTRO sections at the beginning of a QAPIDoc object. Since we have three places that need to insert stub members, take the opportunity to unify and deduplicate this code. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 36 ++++++++--------- scripts/qapi/parser.py | 90 +++++++++++++++++++++++++++--------------- 2 files changed, 75 insertions(+), 51 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 1f7c15b7075..70ab9cdc214 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -349,30 +349,32 @@ def _get_target( ) =20 def visit_sections(self, ent: QAPISchemaDefinition) -> None: + # Generate a placeholder right after the member section(s) which + # will be used to generate documentation for "The members of..." + # pointers in the rendered document. + # This is a temporary hack until the inliner is merged. + if ent.doc: + ent.doc.append_member_stub( + QAPIDoc.ArgSection( + ent.doc.info, QAPIDoc.Kind.MEMBER, "q_dummy" + ) + ) + sections =3D ent.doc.all_sections if ent.doc else [] =20 - # Determine the index location at which we should generate - # documentation for "The members of ..." pointers. This should - # go at the end of the members section(s) if any. Note that - # index 0 is assumed to be a plain intro section, even if it is - # empty; and that a members section if present will always - # immediately follow the opening PLAIN section. - gen_index =3D 1 - if len(sections) > 1: - while sections[gen_index].kind =3D=3D QAPIDoc.Kind.MEMBER: - gen_index +=3D 1 - if gen_index >=3D len(sections): - break - # Add sections in source order: - for i, section in enumerate(sections): + for section in sections: section.text =3D self.reformat_arobase(section.text) =20 if section.kind.name in ("PLAIN", "INTRO"): self.visit_paragraph(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) - self.visit_member(section) + if section.name =3D=3D "q_dummy": + # Generate "The members of ..." entries if necessary + self._insert_member_pointer(ent) + else: + self.visit_member(section) elif section.kind =3D=3D QAPIDoc.Kind.FEATURE: assert isinstance(section, QAPIDoc.ArgSection) self.visit_feature(section) @@ -386,10 +388,6 @@ def visit_sections(self, ent: QAPISchemaDefinition) ->= None: else: assert False =20 - # Generate "The members of ..." entries if necessary: - if i =3D=3D gen_index - 1: - self._insert_member_pointer(ent) - self.ensure_blank_line() =20 # Transmogrification core methods diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 97e7dacb0fd..b21796b3e80 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -816,6 +816,58 @@ def new_feature(self, info: QAPISourceInfo, name: str)= -> None: def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) =20 + def _insert_near_kind( + self, + kind: 'QAPIDoc.Kind', + new_sect: 'QAPIDoc.Section', + after: bool =3D False, + ) -> bool: + """Insert or append a new doc section at a specific point.""" + for idx, sect in enumerate(reversed(self.all_sections)): + if sect.kind =3D=3D kind: + pos =3D len(self.all_sections) - idx - 1 + if after: + pos +=3D 1 + self.all_sections.insert(pos, new_sect) + return True + return False + + def _insert_after_intro( + self, + section: 'QAPIDoc.Section', + ) -> None: + """ + Insert a section immediately after the intro section. + + While we convert PLAIN sections to INTRO sections, all + contiguous INTRO/PLAIN sections at the start of a QAPIDoc + section list are treated as "the intro". + + Once INTRO conversion is complete, this helper will no longer be + needed and ``_insert_near_kind(QAPIDoc.Kind.INTRO, ...)`` will + be sufficient. + """ + index =3D 0 + for index, ref_section in enumerate(self.all_sections): + if ref_section.kind.name in ("PLAIN", "INTRO"): + continue + break + else: + index +=3D 1 + + self.all_sections.insert(index, section) + + def append_member_stub(self, stub: 'QAPIDoc.Section') -> None: + + """ + Append a stub section after any Member sections. + """ + if self._insert_near_kind(QAPIDoc.Kind.MEMBER, stub, True): + return + + # No MEMBER sections present. Insert after INTRO/PLAIN sections. + self._insert_after_intro(stub) + def connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self._args: assert member.info @@ -825,20 +877,10 @@ def connect_member(self, member: 'QAPISchemaMember') = -> None: % (member.role, member.name)) # Insert stub documentation section for missing member docs. # TODO: drop when undocumented members are outlawed - - section =3D QAPIDoc.ArgSection( + stub_section =3D QAPIDoc.ArgSection( self.info, QAPIDoc.Kind.MEMBER, member.name) - self._args[member.name] =3D section - - # Determine where to insert stub doc - it should go at the - # end of the members section(s), if any. Note that index 0 - # is assumed to be an untagged intro section, even if it is - # empty. - index =3D 1 - if len(self.all_sections) > 1: - while self.all_sections[index].kind =3D=3D QAPIDoc.Kind.ME= MBER: - index +=3D 1 - self.all_sections.insert(index, section) + self._args[member.name] =3D stub_section + self.append_member_stub(stub_section) =20 self._args[member.name].connect(member) =20 @@ -851,27 +893,13 @@ def connect_feature(self, feature: 'QAPISchemaFeature= ') -> None: =20 def ensure_returns(self, info: QAPISourceInfo) -> None: =20 - def _insert_near_kind( - kind: QAPIDoc.Kind, - new_sect: QAPIDoc.Section, - after: bool =3D False, - ) -> bool: - for idx, sect in enumerate(reversed(self.all_sections)): - if sect.kind =3D=3D kind: - pos =3D len(self.all_sections) - idx - 1 - if after: - pos +=3D 1 - self.all_sections.insert(pos, new_sect) - return True - return False - if any(s.kind =3D=3D QAPIDoc.Kind.RETURNS for s in self.all_sectio= ns): return =20 # Stub "Returns" section for undocumented returns value stub =3D QAPIDoc.Section(info, QAPIDoc.Kind.RETURNS) =20 - if any(_insert_near_kind(kind, stub, after) for kind, after in ( + if any(self._insert_near_kind(kind, stub, after) for kind, after i= n ( # 1. If arguments, right after those. (QAPIDoc.Kind.MEMBER, True), # 2. Elif errors, right *before* those. @@ -881,10 +909,8 @@ def _insert_near_kind( )): return =20 - # Otherwise, it should go right after the intro. The intro - # is always the first section and is always present (even - # when empty), so we can insert directly at index=3D1 blindly. - self.all_sections.insert(1, stub) + # Otherwise, it should go right after the intro. + self._insert_after_intro(stub) =20 def check_expr(self, expr: QAPIExpression) -> None: if 'command' in expr: --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490880; cv=none; d=zohomail.com; s=zohoarc; b=UDMdEKsA8iTgG1oU7Rf0Cb8DHuQwgYfHdKSZ3LSTYB7+7jECP0e3VO7UGHpOnUTr0mcqzeSk8G7SwHuNC0F9fMMds3Fdtzk7RXcL9671iDZ8fNPaZVk4L9HBcQfAQZqkhOfjMNKEUpYNibemRSO2s9Xf4s/JXLhZjo4PUGAXwdA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490880; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=5KyCe0YgaCTl5zAFMYZ3oDlDsNQVtLgOU9+i6C3wwjc=; b=KmaT4/75jmQ6wT8wfl3CmfgKcwVmi7kj97mXAG9e3yKjXYSkGwbDxVZR8PCShjrjbiHHUpVGmIVhCIEG4zGNne0vSUQGEjHeaUQ+nSiya/VHG2nsrUVOLGcsGP+Zl2cDNizgmY1TrRR7Zscti9NJAeIY+G3CQ5fjQ/DPjkZEBKM= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490880893297.215600017316; Wed, 29 Apr 2026 12:28:00 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZZ-0007QY-Ii; Wed, 29 Apr 2026 15:27:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYi-0006bN-MD for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:57 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYg-0007sA-Hk for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:55 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-365-QNkvp3pYMRWAkE3WlFEuYA-1; Wed, 29 Apr 2026 15:26:44 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D3F8519560A6; Wed, 29 Apr 2026 19:26:42 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C68451800446; Wed, 29 Apr 2026 19:26:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490807; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=5KyCe0YgaCTl5zAFMYZ3oDlDsNQVtLgOU9+i6C3wwjc=; b=fMEEm7B8Zc6aCoTKQswrJAoioWTJT3kDYdEVHCmzqjcuq8fX6zWcOsuEzbVfGdQJTcKEAV Cx03/GAND7hdRuBdaIVK3byzdu9u6SoaWFAivCn9nzRxy9RyCtthps/yFVF+/DSR1S/f9t ibDUppjr9LGe4Rn/8mInEq4ErUWX7m4= X-MC-Unique: QNkvp3pYMRWAkE3WlFEuYA-1 X-Mimecast-MFC-AGG-ID: QNkvp3pYMRWAkE3WlFEuYA_1777490803 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 06/13] qapi/docs: remove implicit Plain section Date: Wed, 29 Apr 2026 15:26:04 -0400 Message-ID: <20260429192611.1581223-7-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490881624158500 Content-Type: text/plain; charset="utf-8" Prior to this patch, we always instantiate an empty Plain section. Removing this allows us to gradually phase out the "Plain" section in favor of "Intro" and "Details" sections while keeping "Plain" around for the interim churn during the series - meaning that we don't actually know at __init__ time which type of section we'll have first. Signed-off-by: John Snow --- scripts/qapi/parser.py | 4 +--- tests/qapi-schema/doc-good.out | 14 -------------- 2 files changed, 1 insertion(+), 17 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b21796b3e80..6612f471bb8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -730,9 +730,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): # definition doc's symbol, None for free-form doc self.symbol: Optional[str] =3D symbol # the sections in textual order - self.all_sections: List[QAPIDoc.Section] =3D [ - QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) - ] + self.all_sections: List[QAPIDoc.Section] =3D [] # dicts mapping parameter/feature names to their description self._args: Dict[str, QAPIDoc.ArgSection] =3D {} self._features: Dict[str, QAPIDoc.ArgSection] =3D {} diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index e2be6f96bbf..6fcc8175cfe 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -106,8 +106,6 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum - section=3DPlain - arg=3Done The _one_ {and only}, description on the same line arg=3Dtwo @@ -119,8 +117,6 @@ a member feature section=3DPlain @two is undocumented doc symbol=3DBase - section=3DPlain - arg=3Dbase1 description starts on a new line, minimally indented @@ -138,16 +134,10 @@ a feature feature=3Dmember-feat a member feature doc symbol=3DVariant2 - section=3DPlain - doc symbol=3DObject - section=3DPlain - feature=3Dunion-feat1 a feature doc symbol=3DAlternate - section=3DPlain - arg=3Di description starts on the same line remainder indented the same @@ -161,8 +151,6 @@ doc freeform Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd - section=3DPlain - arg=3Darg1 description starts on a new line, indented @@ -223,7 +211,5 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED - section=3DPlain - feature=3Dfeat3 a feature --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490866; cv=none; d=zohomail.com; s=zohoarc; b=TyEJx0RsihlllSfFOGj3u+NqCev4wuJseXBA5Pr/cAgIgSs9t15LoOXJ9gzo12+tWneWk1V2aPGLojqCUUMlbdzRUyzlMmSGw9f0mCg5PKoTuKPGnbUD0Duesvkb7bqgFvfnWLZym0Hv/NtkNGlIARUkjYTO9ll+SCsL95EZ7D8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490866; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=1RnXeAmATeyUsCopnaMFFVo+LSjz0TqZZY4sjNLz9vY=; b=W+Ct/yCnVb51GUXX4xJTNw0zX3/2/2v+JdmNppP15EymFNChfpwhE+W+nf6RbUTmdDL6OChfvLYJDJEYCAHNnNUxIZNasqIiNBc3/0gHuxE6JGaMG+rGPE+V3o/FGpco9P6Dcsfxz67zmpt64l/AYD7LWNHPyY5CyME8Gf3AkBg= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17774908660411019.8256596370663; Wed, 29 Apr 2026 12:27:46 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZ1-0006w3-B5; Wed, 29 Apr 2026 15:27:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYk-0006dq-3q for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:58 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYg-0007sR-O1 for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:57 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-652-2QSOeb1GMZOdyx3_-gz6SA-1; Wed, 29 Apr 2026 15:26:47 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 797A21800364; Wed, 29 Apr 2026 19:26:46 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 17C9C180034F; Wed, 29 Apr 2026 19:26:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490811; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=1RnXeAmATeyUsCopnaMFFVo+LSjz0TqZZY4sjNLz9vY=; b=SrujbOvbAxksVJA/mJDide/vNR008rvkG422sCrPJeD1PH2DHwH0lteQid1Y4wls1CJ8vk 2qOZcpDwKICqBbvVbKoc1snxKzPU5lDsG6Cd3uKF2DxDdEWXuW6JACeszTvUDb8rCl82CW pFW6lA1CHsLXymRae3ETnOGpSoX6G9E= X-MC-Unique: 2QSOeb1GMZOdyx3_-gz6SA-1 X-Mimecast-MFC-AGG-ID: 2QSOeb1GMZOdyx3_-gz6SA_1777490806 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 07/13] qapi/docs: add "Intro" section parsing Date: Wed, 29 Apr 2026 15:26:05 -0400 Message-ID: <20260429192611.1581223-8-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490867576158500 Content-Type: text/plain; charset="utf-8" Add parsing for explicit Intro section syntax. A side effect of this patch is that we will always create an empty Intro section, similar to how we used to have an empty Plain section. The tests are adjusted accordingly, rendered document output does not change at all. Signed-off-by: John Snow --- docs/devel/qapi-code-gen.rst | 17 +++++---- scripts/qapi/parser.py | 47 ++++++++++++++++++------- tests/qapi-schema/doc-good.out | 18 ++++++++++ tests/qapi-schema/doc-missing-colon.err | 2 +- 4 files changed, 64 insertions(+), 20 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 3a632b4a648..a8175934d52 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -862,7 +862,7 @@ documentation comment. If the documentation comment starts like :: =20 ## - # @SYMBOL: + # @SYMBOL: [...] =20 it documents the definition of SYMBOL, else it's free-form documentation. @@ -984,11 +984,11 @@ definition it documents. When documentation is required (see pragma_ 'doc-required'), every definition must have documentation. =20 -Definition documentation starts with a line naming the definition, -followed by an optional overview, a description of each argument (for -commands and events), member (for structs and unions), branch (for -alternates), or value (for enums), a description of each feature (if -any), and finally optional tagged sections. +Definition documentation starts with a description naming the definition +with an optional overview, a description of each argument (for commands +and events), member (for structs and unions), branch (for alternates), +or value (for enums), a description of each feature (if any), and +finally optional tagged sections. =20 Descriptions start with '\@name:'. The description text must be indented like this:: @@ -996,6 +996,11 @@ indented like this:: # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. =20 +Definition descriptions are special: the optional introductory overview +describing the definition will not be inlined when referenced by other +definitions (such as when using 'base' to include members from another +definition), while other descriptions and tagged sections will be. + .. FIXME The parser accepts these things in almost any order. =20 .. FIXME union branches should be described, too. diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 6612f471bb8..c23fd26aaa7 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -24,6 +24,7 @@ Match, Optional, Set, + Tuple, Union, ) =20 @@ -524,6 +525,30 @@ def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optiona= l[str]: return line doc.append_line(line) =20 + def _get_doc_intro( + self, + line: str, + info: QAPISourceInfo + ) -> Tuple['QAPIDoc', Optional[str]]: + match =3D self._match_at_name_colon(line) + if not match: + raise QAPIParseError(self, "@name must end with ':'") + + # Invalid names are not checked here, but the name + # provided *must* match the following definition, + # which *is* validated in expr.py. + symbol =3D match.group(1) + if not symbol: + raise QAPIParseError(self, "name required after '@'") + doc =3D QAPIDoc(info, symbol) + + doc.ensure_untagged_section(info, QAPIDoc.Kind.INTRO) + text =3D line[match.end():] + if text: + doc.append_line(text) + + return doc, self.get_doc_indented(doc) + def get_doc(self) -> 'QAPIDoc': if self.val !=3D '##': raise QAPIParseError( @@ -532,18 +557,9 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line =3D self.get_doc_line() if line is not None and line.startswith('@'): + # Definition documentation - if not line.endswith(':'): - raise QAPIParseError(self, "line should end with ':'") - # Invalid names are not checked here, but the name - # provided *must* match the following definition, - # which *is* validated in expr.py. - symbol =3D line[1:-1] - if not symbol: - raise QAPIParseError(self, "name required after '@'") - doc =3D QAPIDoc(info, symbol) - self.accept(False) - line =3D self.get_doc_line() + doc, line =3D self._get_doc_intro(line, info) no_more_args =3D False =20 while line is not None: @@ -751,8 +767,13 @@ def end(self) -> None: raise QAPISemError( section.info, "text required after '%s:'" % section.ki= nd) =20 - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: - kind =3D QAPIDoc.Kind.PLAIN + def ensure_untagged_section( + self, + info: QAPISourceInfo, + kind: Optional['QAPIDoc.Kind'] =3D None, + ) -> None: + if kind is None: + kind =3D QAPIDoc.Kind.PLAIN =20 if self.all_sections and self.all_sections[-1].kind =3D=3D kind: # extend current section diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 6fcc8175cfe..bc89853765f 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -106,6 +106,8 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum + section=3DIntro + arg=3Done The _one_ {and only}, description on the same line arg=3Dtwo @@ -117,10 +119,14 @@ a member feature section=3DPlain @two is undocumented doc symbol=3DBase + section=3DIntro + arg=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 + section=3DIntro + section=3DPlain A paragraph =20 @@ -134,10 +140,16 @@ a feature feature=3Dmember-feat a member feature doc symbol=3DVariant2 + section=3DIntro + doc symbol=3DObject + section=3DIntro + feature=3Dunion-feat1 a feature doc symbol=3DAlternate + section=3DIntro + arg=3Di description starts on the same line remainder indented the same @@ -151,6 +163,8 @@ doc freeform Another subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D doc symbol=3Dcmd + section=3DIntro + arg=3Darg1 description starts on a new line, indented @@ -198,6 +212,8 @@ Note:: section=3DSince 2.10 doc symbol=3Dcmd-boxed + section=3DIntro + section=3DPlain If you're bored enough to read this, go see a video of boxed cats feature=3Dcmd-feat1 @@ -211,5 +227,7 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED + section=3DIntro + feature=3Dfeat3 a feature diff --git a/tests/qapi-schema/doc-missing-colon.err b/tests/qapi-schema/do= c-missing-colon.err index cbcea007153..bd5862b30f3 100644 --- a/tests/qapi-schema/doc-missing-colon.err +++ b/tests/qapi-schema/doc-missing-colon.err @@ -1 +1 @@ -doc-missing-colon.json:4:1: line should end with ':' +doc-missing-colon.json:4:1: @name must end with ':' --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490868; cv=none; d=zohomail.com; s=zohoarc; b=YdzpAfir1O/ClJiVoCkky5OVLmInDYKp4VwbXL3VCcXDz+sqtE2StKmBRqYpsy7qyR6sn7TbNSDt68uPZ/INham1FgkxDXIyDWFSllTZnKiXOXrcJCnPOG29IMqlSsedhL3At9r/tbsrbk6cTi/8YLy0djWIhHYU/zB/HGHOAl0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490868; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=+IlVVKtNcBZg/WOApfTWZgKHPvH/4hX4GeKENZAPe3Y=; b=BHbrDKkhupMd8qxhGvJeVTNqrGRw9iZebZxCNFqOx9JtgLo6XASOLxM0H+IRZEscTJIxGhBTo3eoToz7nP2KKbFrPT/a/uQOvyPfl1ZaQI06J+54xzEcy9k1CMyp0wiNPVqA4sD+yRWqJ/w0fkDcb12FHKyYeujYOR4HPH2fmgo= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490868972308.58997635342587; Wed, 29 Apr 2026 12:27:48 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZ1-0006wk-DV; Wed, 29 Apr 2026 15:27:15 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYl-0006gk-VH for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:00 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYj-0007sx-SL for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:26:59 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-332-Gq1PGyQtNECCdIVpC9I0zQ-1; Wed, 29 Apr 2026 15:26:51 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 57F9E19560A5; Wed, 29 Apr 2026 19:26:50 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B037C1800446; Wed, 29 Apr 2026 19:26:46 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490816; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=+IlVVKtNcBZg/WOApfTWZgKHPvH/4hX4GeKENZAPe3Y=; b=IunLrhFv9oOX3vsXsBPuHnJJaDEH0s1TADwoWj5ekJXoVw2owJtCox3CONJTT+EWrOl4bw K//3BQFS/mFBtTJIVENrK2TWSSkGeOoFqNFs7bcTeYdLGJLPp3QLfcUDEteZqT4tg5VveZ s25c+JIdc/KvVIhLqf3CuZEmu+08jFE= X-MC-Unique: Gq1PGyQtNECCdIVpC9I0zQ-1 X-Mimecast-MFC-AGG-ID: Gq1PGyQtNECCdIVpC9I0zQ_1777490810 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 08/13] qapi/docs: Add rendering for INTRO sections Date: Wed, 29 Apr 2026 15:26:06 -0400 Message-ID: <20260429192611.1581223-9-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490871625154100 Content-Type: text/plain; charset="utf-8" The only real difference here is that we need to dedent all but the first line so that it renders correctly. We don't need to do this for members and features because they are always rendered as part of a field list directive which expects indented lines - Undecorated plaintext doesn't, so we chop the indent off. This does not reflow the text or mess with the source info in any way, so "blame" for error messages should be unchanged. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 14 +++++++++++--- 1 file changed, 11 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 70ab9cdc214..6b8e4ecd76a 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -35,6 +35,7 @@ from pathlib import Path import re import sys +import textwrap from typing import TYPE_CHECKING =20 from docutils import nodes @@ -150,8 +151,14 @@ def add_lines( self, content: str, info: QAPISourceInfo, + dedent: bool =3D False, ) -> None: lines =3D content.splitlines(True) + + if dedent: + txt =3D "".join(lines[1:]) + lines[1:] =3D textwrap.dedent(txt).splitlines(True) + for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) =20 @@ -223,13 +230,14 @@ def reformat_arobase(text: str) -> str: =20 # Transmogrification helpers =20 - def visit_paragraph(self, section: QAPIDoc.Section) -> None: + def visit_text(self, section: QAPIDoc.Section) -> None: # Squelch empty paragraphs. if not section.text: return =20 + dedent =3D bool(section.kind =3D=3D QAPIDoc.Kind.INTRO) self.ensure_blank_line() - self.add_lines(section.text, section.info) + self.add_lines(section.text, section.info, dedent) self.ensure_blank_line() =20 def visit_member(self, section: QAPIDoc.ArgSection) -> None: @@ -367,7 +375,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> = None: section.text =3D self.reformat_arobase(section.text) =20 if section.kind.name in ("PLAIN", "INTRO"): - self.visit_paragraph(section) + self.visit_text(section) elif section.kind =3D=3D QAPIDoc.Kind.MEMBER: assert isinstance(section, QAPIDoc.ArgSection) if section.name =3D=3D "q_dummy": --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490919; cv=none; d=zohomail.com; s=zohoarc; b=kt7vrSIK+B0G8P/Zrz896/NhflIO0bc9n1c5U+KCSMLQZEv/JfjVw07iMKCDKknZ5xOwZtcg9+Cg9Lld7+EfWW2vz8yKiDGSmctxr0x4wFrPSOvH+QHd/B5aGIRCvVqzatH1po+ho1gWAszYA2dWaIco/PvJ/M9v5PWd1cxR094= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490919; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=NSTrmcdDV2VoMJthdCMHqXRFRr9NpkQNPIiunlsA62I=; b=aZwXxPZGsedcJgNkr5f1GWKSq1KoViaWEh52rjKQ5JKF1qIrTrNf8j5k/QJ7LvZgqejCU+WbyEP0qT8qqJ5hHSwXFJh8r9VaJGFIIleHzmB4N1KJztjclwqZmLhLDBrJU6DZY2b3S8xMpUVT9pJrqGYlZ3jUAZFlCzYqqsjFE00= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490919836709.0030987437724; Wed, 29 Apr 2026 12:28:39 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZy-0007wB-T8; Wed, 29 Apr 2026 15:28:20 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYn-0006ht-3K for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:03 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYl-0007tW-OA for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:00 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-496-ZQ8QttCMOVKIUWwdOujvqA-1; Wed, 29 Apr 2026 15:26:55 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id ED90919560A7; Wed, 29 Apr 2026 19:26:53 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8FDB9180034F; Wed, 29 Apr 2026 19:26:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490818; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=NSTrmcdDV2VoMJthdCMHqXRFRr9NpkQNPIiunlsA62I=; b=BbLlB5pzA7hYCyaqBjxDMxJsDV670oFAL4iuGmDtaK2RpsSP4RAMa3Li7vHdzyJlqqPHhg mxuW25Rqy76TMRD8y50rwzYgU0a/UhOaQ1P+K490qq4wSOk1TSUH4IM00cHf3lBT3IKgGf kwXdjefJyTzjUqU2qG9iVnTfnlI8ZK4= X-MC-Unique: ZQ8QttCMOVKIUWwdOujvqA-1 X-Mimecast-MFC-AGG-ID: ZQ8QttCMOVKIUWwdOujvqA_1777490814 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 09/13] qapi: convert intro sections for accelerator.json Date: Wed, 29 Apr 2026 15:26:07 -0400 Message-ID: <20260429192611.1581223-10-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490922210154100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/accelerator.json | 24 ++++++------------------ 1 file changed, 6 insertions(+), 18 deletions(-) diff --git a/qapi/accelerator.json b/qapi/accelerator.json index 0cf5e0f9d94..71047538ee1 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -12,9 +12,7 @@ { 'include': 'common.json' } =20 ## -# @KvmInfo: -# -# Information about support for KVM acceleration +# @KvmInfo: Information about support for KVM acceleration # # @enabled: true if KVM acceleration is active # @@ -25,9 +23,7 @@ { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } =20 ## -# @query-kvm: -# -# Return information about KVM acceleration +# @query-kvm: Return information about KVM acceleration # # Since: 0.14 # @@ -39,9 +35,7 @@ { 'command': 'query-kvm', 'returns': 'KvmInfo' } =20 ## -# @x-accel-stats: -# -# Query accelerator statistics +# @x-accel-stats: Query accelerator statistics # # Features: # @@ -56,9 +50,7 @@ 'features': [ 'unstable' ] } =20 ## -# @Accelerator: -# -# Information about support for MSHV acceleration +# @Accelerator: Information about support for MSHV acceleration # # @hvf: Apple Hypervisor.framework # @@ -81,9 +73,7 @@ { 'enum': 'Accelerator', 'data': ['hvf', 'kvm', 'mshv', 'nvmm', 'qtest', '= tcg', 'whpx', 'xen'] } =20 ## -# @AcceleratorInfo: -# -# Information about support for various accelerators +# @AcceleratorInfo: Information about support for various accelerators # # @enabled: the accelerator that is in use # @@ -95,9 +85,7 @@ { 'struct': 'AcceleratorInfo', 'data': {'enabled': 'Accelerator', 'present= ': ['Accelerator']} } =20 ## -# @query-accelerators: -# -# Return information about accelerators +# @query-accelerators: Return information about accelerators # # Returns: @AcceleratorInfo # --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490863; cv=none; d=zohomail.com; s=zohoarc; b=Ni68rmhGjqwKJYqtCCHNm0+osP/N/Z43K9iRqEh3SAbiAysHuGcZzicYELo/+6nJft2/QZ8ENvOIYG6snbNC7X0r2qSP89E/qcOgwFrsTZce0qFaXkX1L9lSF7PhH5B83ub8xzxVTB3rUcUYgxtXm+o4XWLP/DlpYfGn97sqRpU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490863; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=queDKcMKQuUxsPxmAazGxg352qnq/byirb1cxSoH2OY=; b=Xl9X5L9DXD/6Zw0gCGqNsqobI1NJecyvhjoaZGGQ9gmJKwmgPr2gAsgiCt+QbDWPhIzNPj1bSjuHaf4gzpVNj1UPsiXqjpDS//4jN1DVAG01Me5V56XskIEatajsbRB/lvzl28ZCPmveD3T8NVrgS3G5RJDrl3duagXNmX2Y0Jw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490863376571.3246641090267; Wed, 29 Apr 2026 12:27:43 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZ2-00072x-BK; Wed, 29 Apr 2026 15:27:16 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYr-0006im-7N for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:05 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYp-0007uH-UA for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:04 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-12-UJ2ASGagOneuKaduOUSFXA-1; Wed, 29 Apr 2026 15:26:59 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 69D7D195608F; Wed, 29 Apr 2026 19:26:58 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 8FDDE180045E; Wed, 29 Apr 2026 19:26:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490823; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=queDKcMKQuUxsPxmAazGxg352qnq/byirb1cxSoH2OY=; b=QBmG7TvV62elNf5l9aa4phUy8FjyYRF8dUwdGKINx2uWI/VVrZrzlf2pu5Xm9gtqUAxIvU pB2cjQEV+TcKCI7QvKi7D6pGGU8tKPrcvFcQgkCqZlrygAKS3UyGVUke12UhMq6dr0L61i pnGz+h5lIC9sTA1AlPKGJDCYuD+bbWg= X-MC-Unique: UJ2ASGagOneuKaduOUSFXA-1 X-Mimecast-MFC-AGG-ID: UJ2ASGagOneuKaduOUSFXA_1777490818 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 10/13] qapi: convert intro sections for acpi-hest.json Date: Wed, 29 Apr 2026 15:26:08 -0400 Message-ID: <20260429192611.1581223-11-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490865410154100 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/acpi-hest.json | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json index a01f1dee095..6a48e80082e 100644 --- a/qapi/acpi-hest.json +++ b/qapi/acpi-hest.json @@ -12,9 +12,8 @@ ## =20 ## -# @inject-ghes-v2-error: -# -# Inject an error with additional ACPI 6.1 GHESv2 error information +# @inject-ghes-v2-error: Inject an error with additional ACPI 6.1 +# GHESv2 error information # # @cper: contains a base64 encoded string with raw data for a single # CPER record with Generic Error Status Block, Generic Error Data --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490890; cv=none; d=zohomail.com; s=zohoarc; b=g841sZhn6hoO4k2qLLRywbq0O1b04A4aDwwhgLToHwPLwqvzTim36kC8XCm+occRw30huKUbae0QMUM2pGNJM547vdspR7rWxJR+GC3+JVhbSftBV3kuM1JqUGI0NtVsm4hdZt6ufbdB2jgnLpt5H3TI8NpSuAa7r7za1/BLy54= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490890; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=3shFO9TU/6Blv38nqVoZBtp3uUmYYmGGymP1Ao4ilxg=; b=hbkUlg1CFFqXRquqbAUo38hBa3D+ZAurjFzkr7mghlCOQqa/byaFuyxAHbU88WLvIeQupJB/uQdkzANQ+yfhYDnCPnQhgvH6ThdVRdTCOsiDA9BwzMdJjnOulI62UmZYwauukYWXCvMsH130Rsmr9eB+TW2xJkHkILceBWDjzaw= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490890491834.2074823181648; Wed, 29 Apr 2026 12:28:10 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAZU-0007N3-VK; Wed, 29 Apr 2026 15:27:48 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAZ2-00073b-8D for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:16 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAYv-0007ve-BI for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:15 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-693-hIHyYKOOO8Od4OTFQngw_w-1; Wed, 29 Apr 2026 15:27:05 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3C174195608F; Wed, 29 Apr 2026 19:27:04 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A17FD180045E; Wed, 29 Apr 2026 19:26:58 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490827; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=3shFO9TU/6Blv38nqVoZBtp3uUmYYmGGymP1Ao4ilxg=; b=J5L/C1cp4oRyv6jd+i6PifB+dYdKGgRKTYRPTXVTOUicR0oODkxGT6aJmUswX5uYrtgvf9 PXB3QtWa2XbNfhCKWYURywj5morV74g/pBUxhJGM1BIPBHB0HnxBOfGJwNMSsClpOpzOW1 7T2fcuo4jzfTTBizppqXMnuetLW1NZM= X-MC-Unique: hIHyYKOOO8Od4OTFQngw_w-1 X-Mimecast-MFC-AGG-ID: hIHyYKOOO8Od4OTFQngw_w_1777490824 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 11/13] qapi: convert intro sections for acpi.json Date: Wed, 29 Apr 2026 15:26:09 -0400 Message-ID: <20260429192611.1581223-12-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490891592158500 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/acpi.json | 23 ++++++++--------------- 1 file changed, 8 insertions(+), 15 deletions(-) diff --git a/qapi/acpi.json b/qapi/acpi.json index 906b3687a55..ea6ad2cd45f 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -12,9 +12,8 @@ ## =20 ## -# @AcpiTableOptions: -# -# Specify an ACPI table on the command line to load. +# @AcpiTableOptions: Specify an ACPI table on the +# command line to load. # # At most one of @file and @data can be specified. The list of files # specified by any one of them is loaded and concatenated in order. @@ -80,11 +79,9 @@ { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } =20 ## -# @ACPIOSTInfo: -# -# OSPM Status Indication for a device. For description of possible -# values of @source and @status fields see "_OST (OSPM Status -# Indication)" chapter of ACPI5.0 spec. +# @ACPIOSTInfo: OSPM Status Indication for a device. For description +# of possible values of @source and @status fields see "_OST (OSPM +# Status Indication)" chapter of ACPI5.0 spec. # # @device: device ID associated with slot # @@ -106,10 +103,8 @@ 'status': 'int' } } =20 ## -# @query-acpi-ospm-status: -# -# Return a list of `ACPIOSTInfo` for devices that support status -# reporting via ACPI _OST method. +# @query-acpi-ospm-status: Return a list of `ACPIOSTInfo` for devices +# that support status reporting via ACPI _OST method. # # Since: 2.1 # @@ -125,9 +120,7 @@ { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } =20 ## -# @ACPI_DEVICE_OST: -# -# Emitted when guest executes ACPI _OST method. +# @ACPI_DEVICE_OST: Emitted when guest executes ACPI _OST method. # # @info: OSPM Status Indication # --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490932; cv=none; d=zohomail.com; s=zohoarc; b=Lh4Gtqxk5ybdzdu4sMVz9tohAOQqkXemmDsToTEoH1p79Yg/AK0WM2hU7lIIlsH60Xnfgln7IOzUemHm9Cqhxeulcgxh8Lqv9C6FGlHZj5pRzuWsnxmC0yo+cFnokyz2cD/uFsqxUxedQx9L4KH86sg1+iF5mp6+nIin6lRSCVw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490932; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=97OMNLdbAx+/ZvtUpM/tGpC1iMEpd6AAQW6MJCrh2N8=; b=gYu5rXWPT1YUxzFVnQaKThIB8LX7yE4qHgRcb5/eyb3Iy7de98ynIRtoYLxoiDnrsrEtmtyIcWn/rWodY/rLiwTdqX65dZFPyZFkEcV3Zipa5SAWQ7HxjJ6kmyf3RkujrjEVgS3VThKjwaa0g0XIRiSCXlFzKOOGRzH82Q9WJTU= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490932337698.6683001185792; Wed, 29 Apr 2026 12:28:52 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAa8-00085v-88; Wed, 29 Apr 2026 15:28:28 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAZ2-00075o-RF for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:17 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAZ0-0007x7-M5 for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:16 -0400 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-263-UXGHwF8DMuixLuLu0OsqGw-1; Wed, 29 Apr 2026 15:27:09 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 2C775195608B; Wed, 29 Apr 2026 19:27:08 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id AA6421800446; Wed, 29 Apr 2026 19:27:04 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490833; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=97OMNLdbAx+/ZvtUpM/tGpC1iMEpd6AAQW6MJCrh2N8=; b=fZ4B1mXDwKlnFRFJMZb4vgqgn/KvOCPmF0eaCH/dqKlcnm8763KmX2S4RJni+6j5HIq6yk 5N1zbCejBQgNN09oMf/foomdhztXnGHWyLUdIlkkSMswogehrla2YtWwlDHeq11SWTOb5w V98jgA+o80BsjZE+zwiZEj13xbzl0tE= X-MC-Unique: UXGHwF8DMuixLuLu0OsqGw-1 X-Mimecast-MFC-AGG-ID: UXGHwF8DMuixLuLu0OsqGw_1777490828 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 12/13] qapi: convert intro sections for audio.json Date: Wed, 29 Apr 2026 15:26:10 -0400 Message-ID: <20260429192611.1581223-13-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 12 X-Spam_score: 1.2 X-Spam_bar: + X-Spam_report: (1.2 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=no autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490933872158501 Content-Type: text/plain; charset="utf-8" Signed-off-by: John Snow --- qapi/audio.json | 112 ++++++++++++++---------------------------------- 1 file changed, 32 insertions(+), 80 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 2df87b97101..62d64eabf1c 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -13,10 +13,8 @@ ## =20 ## -# @AudiodevPerDirectionOptions: -# -# General audio backend options that are used for both playback and -# recording. +# @AudiodevPerDirectionOptions: General audio backend options that are +# used for both playback and recording. # # @mixing-engine: use QEMU's mixing engine to mix all streams inside # QEMU and convert audio formats when not supported by the @@ -52,9 +50,7 @@ '*buffer-length': 'uint32' } } =20 ## -# @AudiodevGenericOptions: -# -# Generic driver-specific options. +# @AudiodevGenericOptions: Generic driver-specific options. # # @in: options of the capture stream # @@ -68,9 +64,7 @@ '*out': 'AudiodevPerDirectionOptions' } } =20 ## -# @AudiodevDBusOptions: -# -# Options of the D-Bus audio backend. +# @AudiodevDBusOptions: Options of the D-Bus audio backend. # # @in: options of the capture stream # @@ -88,10 +82,8 @@ '*nsamples': 'uint32'} } =20 ## -# @AudiodevAlsaPerDirectionOptions: -# -# Options of the ALSA backend that are used for both playback and -# recording. +# @AudiodevAlsaPerDirectionOptions: Options of the ALSA backend that +# are used for both playback and recording. # # @dev: the name of the ALSA device to use (default 'default') # @@ -110,9 +102,7 @@ '*try-poll': 'bool' } } =20 ## -# @AudiodevAlsaOptions: -# -# Options of the ALSA audio backend. +# @AudiodevAlsaOptions: Options of the ALSA audio backend. # # @in: options of the capture stream # @@ -129,9 +119,7 @@ '*threshold': 'uint32' } } =20 ## -# @AudiodevSndioOptions: -# -# Options of the sndio audio backend. +# @AudiodevSndioOptions: Options of the sndio audio backend. # # @in: options of the capture stream # @@ -151,10 +139,8 @@ '*latency': 'uint32'} } =20 ## -# @AudiodevCoreaudioPerDirectionOptions: -# -# Options of the Core Audio backend that are used for both playback -# and recording. +# @AudiodevCoreaudioPerDirectionOptions: Options of the Core Audio +# backend that are used for both playback and recording. # # @buffer-count: number of buffers # @@ -166,9 +152,7 @@ '*buffer-count': 'uint32' } } =20 ## -# @AudiodevCoreaudioOptions: -# -# Options of the coreaudio audio backend. +# @AudiodevCoreaudioOptions: Options of the coreaudio audio backend. # # @in: options of the capture stream # @@ -182,9 +166,7 @@ '*out': 'AudiodevCoreaudioPerDirectionOptions' } } =20 ## -# @AudiodevDsoundOptions: -# -# Options of the DirectSound audio backend. +# @AudiodevDsoundOptions: Options of the DirectSound audio backend. # # @in: options of the capture stream # @@ -202,10 +184,8 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevJackPerDirectionOptions: -# -# Options of the JACK backend that are used for both playback and -# recording. +# @AudiodevJackPerDirectionOptions: Options of the JACK backend that +# are used for both playback and recording. # # @server-name: select from among several possible concurrent server # instances (default: environment variable $JACK_DEFAULT_SERVER if @@ -236,9 +216,7 @@ '*exact-name': 'bool' } } =20 ## -# @AudiodevJackOptions: -# -# Options of the JACK audio backend. +# @AudiodevJackOptions: Options of the JACK audio backend. # # @in: options of the capture stream # @@ -252,10 +230,8 @@ '*out': 'AudiodevJackPerDirectionOptions' } } =20 ## -# @AudiodevOssPerDirectionOptions: -# -# Options of the OSS backend that are used for both playback and -# recording. +# @AudiodevOssPerDirectionOptions: Options of the OSS backend that are +# used for both playback and recording. # # @dev: file name of the OSS device (default '/dev/dsp') # @@ -274,9 +250,7 @@ '*try-poll': 'bool' } } =20 ## -# @AudiodevOssOptions: -# -# Options of the OSS audio backend. +# @AudiodevOssOptions: Options of the OSS audio backend. # # @in: options of the capture stream # @@ -304,10 +278,8 @@ '*dsp-policy': 'uint32' } } =20 ## -# @AudiodevPaPerDirectionOptions: -# -# Options of the Pulseaudio backend that are used for both playback -# and recording. +# @AudiodevPaPerDirectionOptions: Options of the Pulseaudio backend +# that are used for both playback and recording. # # @name: name of the sink/source to use # @@ -329,9 +301,7 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevPaOptions: -# -# Options of the PulseAudio audio backend. +# @AudiodevPaOptions: Options of the PulseAudio audio backend. # # @in: options of the capture stream # @@ -348,10 +318,8 @@ '*server': 'str' } } =20 ## -# @AudiodevPipewirePerDirectionOptions: -# -# Options of the PipeWire backend that are used for both playback and -# recording. +# @AudiodevPipewirePerDirectionOptions: Options of the PipeWire +# backend that are used for both playback and recording. # # @name: name of the sink/source to use # @@ -373,9 +341,7 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevPipewireOptions: -# -# Options of the PipeWire audio backend. +# @AudiodevPipewireOptions: Options of the PipeWire audio backend. # # @in: options of the capture stream # @@ -389,10 +355,8 @@ '*out': 'AudiodevPipewirePerDirectionOptions' } } =20 ## -# @AudiodevSdlPerDirectionOptions: -# -# Options of the SDL audio backend that are used for both playback and -# recording. +# @AudiodevSdlPerDirectionOptions: Options of the SDL audio backend +# that are used for both playback and recording. # # @buffer-count: number of buffers (default 4) # @@ -404,9 +368,7 @@ '*buffer-count': 'uint32' } } =20 ## -# @AudiodevSdlOptions: -# -# Options of the SDL audio backend. +# @AudiodevSdlOptions: Options of the SDL audio backend. # # @in: options of the recording stream # @@ -420,9 +382,7 @@ '*out': 'AudiodevSdlPerDirectionOptions' } } =20 ## -# @AudiodevWavOptions: -# -# Options of the wav audio backend. +# @AudiodevWavOptions: Options of the wav audio backend. # # @in: options of the capture stream # @@ -439,9 +399,7 @@ '*path': 'str' } } =20 ## -# @AudioFormat: -# -# An enumeration of possible audio formats. +# @AudioFormat: An enumeration of possible audio formats. # # @u8: unsigned 8 bit integer # @@ -463,9 +421,7 @@ 'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] } =20 ## -# @AudiodevDriver: -# -# An enumeration of possible audio backend drivers. +# @AudiodevDriver: An enumeration of possible audio backend drivers. # # @jack: JACK audio backend (since 5.1) # @@ -487,9 +443,7 @@ 'wav' ] } =20 ## -# @Audiodev: -# -# Options of an audio backend. +# @Audiodev: Options of an audio backend. # # @id: identifier of the backend # @@ -533,9 +487,7 @@ 'wav': 'AudiodevWavOptions' } } =20 ## -# @query-audiodevs: -# -# Return information about audiodev configuration +# @query-audiodevs: Return information about audiodev configuration # # Since: 8.0 ## --=20 2.54.0 From nobody Sat May 30 19:21:08 2026 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=quarantine dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1777490917; cv=none; d=zohomail.com; s=zohoarc; b=JliZbox5SiFjHd2zJtRqJh+hFD2tEywzS9JjlrRZ+OXACJEvxaCHHrzT6ydKRCM2hW3szpxZV4iNMJPXw5pCEDm4hdEMdlyqxDD9sJKkVN1LViV9YSU9POLc4j14M45HVwE1GlIecBt1aZQaPWJFxZ7MF9J83u9XlfpEnn+QSQc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1777490917; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=yvQrrTZJip/bbrHJViDv7QteLJ2uq7tVJhjkIuaDuSk=; b=HMabK4VRqxswI+SpWnYA4XAIm/lJpskSrlncmTPhMJVilTYn3RTFPH/j5c0D6T70NHjhhcGQeiO03Qe9Ki8SvO9bHEf0awbPh45H72X624RBDKahHS2YOXH/OXtwv43ZbSWaaVkrhyd8xo9ThPe+XyTJVn2wptqUCJh2nLyWDhQ= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=quarantine dis=none) Return-Path: Received: from lists1p.gnu.org (lists1p.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1777490917341895.7332176086386; Wed, 29 Apr 2026 12:28:37 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wIAaE-00089X-C6; Wed, 29 Apr 2026 15:28:32 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAZ9-0007DR-D7 for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:27 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1wIAZ5-00080B-Fh for qemu-devel@nongnu.org; Wed, 29 Apr 2026 15:27:21 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-345-dmwEv70RP6OK_uyN-fdJbw-1; Wed, 29 Apr 2026 15:27:14 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 4E6371800352; Wed, 29 Apr 2026 19:27:13 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.80.204]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4B75D1800446; Wed, 29 Apr 2026 19:27:08 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1777490838; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=yvQrrTZJip/bbrHJViDv7QteLJ2uq7tVJhjkIuaDuSk=; b=ZS7cNX8fSGRCd23T15k9CfdpWmCKWEMZBf7U5TS/oX76smRZ2C17wfP0aMjCUT7ol9/AO4 y9UWo2l4az6xAdCfFVJWnQ6SwhKNXwEyC1My+QqrWy4Nf5Z9kCF7lOs7PbdFYRXd0h3Zi+ 8yf4nalHo5gYmuXqv71k9zaxvJpv524= X-MC-Unique: dmwEv70RP6OK_uyN-fdJbw-1 X-Mimecast-MFC-AGG-ID: dmwEv70RP6OK_uyN-fdJbw_1777490833 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Eric Blake , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Richard Henderson , John Snow , Paolo Bonzini , Mauro Carvalho Chehab , "Michael S. Tsirkin" , Peter Maydell , Pierrick Bouvier , Igor Mammedov , Gerd Hoffmann , Ani Sinha , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Markus Armbruster Subject: [PATCH v2 13/13] rfc: intro starts on next line Date: Wed, 29 Apr 2026 15:26:11 -0400 Message-ID: <20260429192611.1581223-14-jsnow@redhat.com> In-Reply-To: <20260429192611.1581223-1-jsnow@redhat.com> References: <20260429192611.1581223-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists1p.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: qemu development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1777490918014158500 Content-Type: text/plain; charset="utf-8" Revert some parser changes that had allowed the intro section to start on the same line as the definition name. If we go this route, the changes need to be back-squashed into earlier commits and the qapi-code-gen.rst documentation needs to be rewritten and reworded a little bit. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 5 +- qapi/accelerator.json | 18 +++-- qapi/acpi-hest.json | 5 +- qapi/acpi.json | 13 ++-- qapi/audio.json | 88 ++++++++++++++++--------- scripts/qapi/parser.py | 12 +--- tests/qapi-schema/doc-missing-colon.err | 2 +- 7 files changed, 86 insertions(+), 57 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 6b8e4ecd76a..985954164b0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -156,8 +156,9 @@ def add_lines( lines =3D content.splitlines(True) =20 if dedent: - txt =3D "".join(lines[1:]) - lines[1:] =3D textwrap.dedent(txt).splitlines(True) + lines =3D textwrap.dedent(content).splitlines(True) + else: + lines =3D content.splitlines(True) =20 for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) diff --git a/qapi/accelerator.json b/qapi/accelerator.json index 71047538ee1..05dbef51c5d 100644 --- a/qapi/accelerator.json +++ b/qapi/accelerator.json @@ -12,7 +12,8 @@ { 'include': 'common.json' } =20 ## -# @KvmInfo: Information about support for KVM acceleration +# @KvmInfo: +# Information about support for KVM acceleration # # @enabled: true if KVM acceleration is active # @@ -23,7 +24,8 @@ { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} } =20 ## -# @query-kvm: Return information about KVM acceleration +# @query-kvm: +# Return information about KVM acceleration # # Since: 0.14 # @@ -35,7 +37,8 @@ { 'command': 'query-kvm', 'returns': 'KvmInfo' } =20 ## -# @x-accel-stats: Query accelerator statistics +# @x-accel-stats: +# Query accelerator statistics # # Features: # @@ -50,7 +53,8 @@ 'features': [ 'unstable' ] } =20 ## -# @Accelerator: Information about support for MSHV acceleration +# @Accelerator: +# Information about support for MSHV acceleration # # @hvf: Apple Hypervisor.framework # @@ -73,7 +77,8 @@ { 'enum': 'Accelerator', 'data': ['hvf', 'kvm', 'mshv', 'nvmm', 'qtest', '= tcg', 'whpx', 'xen'] } =20 ## -# @AcceleratorInfo: Information about support for various accelerators +# @AcceleratorInfo: +# Information about support for various accelerators # # @enabled: the accelerator that is in use # @@ -85,7 +90,8 @@ { 'struct': 'AcceleratorInfo', 'data': {'enabled': 'Accelerator', 'present= ': ['Accelerator']} } =20 ## -# @query-accelerators: Return information about accelerators +# @query-accelerators: +# Return information about accelerators # # Returns: @AcceleratorInfo # diff --git a/qapi/acpi-hest.json b/qapi/acpi-hest.json index 6a48e80082e..8db804df197 100644 --- a/qapi/acpi-hest.json +++ b/qapi/acpi-hest.json @@ -12,8 +12,9 @@ ## =20 ## -# @inject-ghes-v2-error: Inject an error with additional ACPI 6.1 -# GHESv2 error information +# @inject-ghes-v2-error: +# Inject an error with additional ACPI 6.1 GHESv2 error +# information # # @cper: contains a base64 encoded string with raw data for a single # CPER record with Generic Error Status Block, Generic Error Data diff --git a/qapi/acpi.json b/qapi/acpi.json index ea6ad2cd45f..82e82d7cf89 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -12,8 +12,8 @@ ## =20 ## -# @AcpiTableOptions: Specify an ACPI table on the -# command line to load. +# @AcpiTableOptions: +# Specify an ACPI table on the command line to load. # # At most one of @file and @data can be specified. The list of files # specified by any one of them is loaded and concatenated in order. @@ -79,7 +79,8 @@ { 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] } =20 ## -# @ACPIOSTInfo: OSPM Status Indication for a device. For description +# @ACPIOSTInfo: +# OSPM Status Indication for a device. For description # of possible values of @source and @status fields see "_OST (OSPM # Status Indication)" chapter of ACPI5.0 spec. # @@ -103,7 +104,8 @@ 'status': 'int' } } =20 ## -# @query-acpi-ospm-status: Return a list of `ACPIOSTInfo` for devices +# @query-acpi-ospm-status: +# Return a list of `ACPIOSTInfo` for devices # that support status reporting via ACPI _OST method. # # Since: 2.1 @@ -120,7 +122,8 @@ { 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] } =20 ## -# @ACPI_DEVICE_OST: Emitted when guest executes ACPI _OST method. +# @ACPI_DEVICE_OST: +# Emitted when guest executes ACPI _OST method. # # @info: OSPM Status Indication # diff --git a/qapi/audio.json b/qapi/audio.json index 62d64eabf1c..72190f20993 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -13,8 +13,9 @@ ## =20 ## -# @AudiodevPerDirectionOptions: General audio backend options that are -# used for both playback and recording. +# @AudiodevPerDirectionOptions: +# General audio backend options that are used for both playback +# and recording. # # @mixing-engine: use QEMU's mixing engine to mix all streams inside # QEMU and convert audio formats when not supported by the @@ -50,7 +51,8 @@ '*buffer-length': 'uint32' } } =20 ## -# @AudiodevGenericOptions: Generic driver-specific options. +# @AudiodevGenericOptions: +# Generic driver-specific options. # # @in: options of the capture stream # @@ -64,7 +66,8 @@ '*out': 'AudiodevPerDirectionOptions' } } =20 ## -# @AudiodevDBusOptions: Options of the D-Bus audio backend. +# @AudiodevDBusOptions: +# Options of the D-Bus audio backend. # # @in: options of the capture stream # @@ -82,8 +85,9 @@ '*nsamples': 'uint32'} } =20 ## -# @AudiodevAlsaPerDirectionOptions: Options of the ALSA backend that -# are used for both playback and recording. +# @AudiodevAlsaPerDirectionOptions: +# Options of the ALSA backend that are used for both playback and +# recording. # # @dev: the name of the ALSA device to use (default 'default') # @@ -102,7 +106,8 @@ '*try-poll': 'bool' } } =20 ## -# @AudiodevAlsaOptions: Options of the ALSA audio backend. +# @AudiodevAlsaOptions: +# Options of the ALSA audio backend. # # @in: options of the capture stream # @@ -119,7 +124,8 @@ '*threshold': 'uint32' } } =20 ## -# @AudiodevSndioOptions: Options of the sndio audio backend. +# @AudiodevSndioOptions: +# Options of the sndio audio backend. # # @in: options of the capture stream # @@ -139,8 +145,9 @@ '*latency': 'uint32'} } =20 ## -# @AudiodevCoreaudioPerDirectionOptions: Options of the Core Audio -# backend that are used for both playback and recording. +# @AudiodevCoreaudioPerDirectionOptions: +# Options of the Core Audio backend that are used for both +# playback and recording. # # @buffer-count: number of buffers # @@ -152,7 +159,8 @@ '*buffer-count': 'uint32' } } =20 ## -# @AudiodevCoreaudioOptions: Options of the coreaudio audio backend. +# @AudiodevCoreaudioOptions: +# Options of the coreaudio audio backend. # # @in: options of the capture stream # @@ -166,7 +174,8 @@ '*out': 'AudiodevCoreaudioPerDirectionOptions' } } =20 ## -# @AudiodevDsoundOptions: Options of the DirectSound audio backend. +# @AudiodevDsoundOptions: +# Options of the DirectSound audio backend. # # @in: options of the capture stream # @@ -184,8 +193,9 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevJackPerDirectionOptions: Options of the JACK backend that -# are used for both playback and recording. +# @AudiodevJackPerDirectionOptions: +# Options of the JACK backend that are used for both playback and +# recording. # # @server-name: select from among several possible concurrent server # instances (default: environment variable $JACK_DEFAULT_SERVER if @@ -216,7 +226,8 @@ '*exact-name': 'bool' } } =20 ## -# @AudiodevJackOptions: Options of the JACK audio backend. +# @AudiodevJackOptions: +# Options of the JACK audio backend. # # @in: options of the capture stream # @@ -230,8 +241,9 @@ '*out': 'AudiodevJackPerDirectionOptions' } } =20 ## -# @AudiodevOssPerDirectionOptions: Options of the OSS backend that are -# used for both playback and recording. +# @AudiodevOssPerDirectionOptions: +# Options of the OSS backend that are used for both playback and +# recording. # # @dev: file name of the OSS device (default '/dev/dsp') # @@ -250,7 +262,8 @@ '*try-poll': 'bool' } } =20 ## -# @AudiodevOssOptions: Options of the OSS audio backend. +# @AudiodevOssOptions: +# Options of the OSS audio backend. # # @in: options of the capture stream # @@ -278,8 +291,9 @@ '*dsp-policy': 'uint32' } } =20 ## -# @AudiodevPaPerDirectionOptions: Options of the Pulseaudio backend -# that are used for both playback and recording. +# @AudiodevPaPerDirectionOptions: +# Options of the Pulseaudio backend that are used for both +# playback and recording. # # @name: name of the sink/source to use # @@ -301,7 +315,8 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevPaOptions: Options of the PulseAudio audio backend. +# @AudiodevPaOptions: +# Options of the PulseAudio audio backend. # # @in: options of the capture stream # @@ -318,8 +333,9 @@ '*server': 'str' } } =20 ## -# @AudiodevPipewirePerDirectionOptions: Options of the PipeWire -# backend that are used for both playback and recording. +# @AudiodevPipewirePerDirectionOptions: +# Options of the PipeWire backend that are used for both playback +# and recording. # # @name: name of the sink/source to use # @@ -341,7 +357,8 @@ '*latency': 'uint32' } } =20 ## -# @AudiodevPipewireOptions: Options of the PipeWire audio backend. +# @AudiodevPipewireOptions: +# Options of the PipeWire audio backend. # # @in: options of the capture stream # @@ -355,8 +372,9 @@ '*out': 'AudiodevPipewirePerDirectionOptions' } } =20 ## -# @AudiodevSdlPerDirectionOptions: Options of the SDL audio backend -# that are used for both playback and recording. +# @AudiodevSdlPerDirectionOptions: +# Options of the SDL audio backend that are used for both playback +# and recording. # # @buffer-count: number of buffers (default 4) # @@ -368,7 +386,8 @@ '*buffer-count': 'uint32' } } =20 ## -# @AudiodevSdlOptions: Options of the SDL audio backend. +# @AudiodevSdlOptions: +# Options of the SDL audio backend. # # @in: options of the recording stream # @@ -382,7 +401,8 @@ '*out': 'AudiodevSdlPerDirectionOptions' } } =20 ## -# @AudiodevWavOptions: Options of the wav audio backend. +# @AudiodevWavOptions: +# Options of the wav audio backend. # # @in: options of the capture stream # @@ -399,7 +419,8 @@ '*path': 'str' } } =20 ## -# @AudioFormat: An enumeration of possible audio formats. +# @AudioFormat: +# An enumeration of possible audio formats. # # @u8: unsigned 8 bit integer # @@ -421,7 +442,8 @@ 'data': [ 'u8', 's8', 'u16', 's16', 'u32', 's32', 'f32' ] } =20 ## -# @AudiodevDriver: An enumeration of possible audio backend drivers. +# @AudiodevDriver: +# An enumeration of possible audio backend drivers. # # @jack: JACK audio backend (since 5.1) # @@ -443,7 +465,8 @@ 'wav' ] } =20 ## -# @Audiodev: Options of an audio backend. +# @Audiodev: +# Options of an audio backend. # # @id: identifier of the backend # @@ -487,7 +510,8 @@ 'wav': 'AudiodevWavOptions' } } =20 ## -# @query-audiodevs: Return information about audiodev configuration +# @query-audiodevs: +# Return information about audiodev configuration # # Since: 8.0 ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c23fd26aaa7..8ff2a2c4c0b 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -530,23 +530,17 @@ def _get_doc_intro( line: str, info: QAPISourceInfo ) -> Tuple['QAPIDoc', Optional[str]]: - match =3D self._match_at_name_colon(line) - if not match: - raise QAPIParseError(self, "@name must end with ':'") + if not line.endswith(':'): + raise QAPIParseError(self, "line should end with ':'") =20 # Invalid names are not checked here, but the name # provided *must* match the following definition, # which *is* validated in expr.py. - symbol =3D match.group(1) + symbol =3D line[1:-1] if not symbol: raise QAPIParseError(self, "name required after '@'") doc =3D QAPIDoc(info, symbol) - doc.ensure_untagged_section(info, QAPIDoc.Kind.INTRO) - text =3D line[match.end():] - if text: - doc.append_line(text) - return doc, self.get_doc_indented(doc) =20 def get_doc(self) -> 'QAPIDoc': diff --git a/tests/qapi-schema/doc-missing-colon.err b/tests/qapi-schema/do= c-missing-colon.err index bd5862b30f3..cbcea007153 100644 --- a/tests/qapi-schema/doc-missing-colon.err +++ b/tests/qapi-schema/doc-missing-colon.err @@ -1 +1 @@ -doc-missing-colon.json:4:1: @name must end with ':' +doc-missing-colon.json:4:1: line should end with ':' --=20 2.54.0