From nobody Sun Jul 26 13:29:04 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=1781619546; cv=none; d=zohomail.com; s=zohoarc; b=TDrdRT6idhUXRFJ6eSQj7KdCRQXTpUG++b4/aOWx3nraaS+QSj2x2VSjIfOLvwjprJ71MEvDtT3MMb7/UrvHqryieqssnhgO2Y58ey1XGKwKIntRYYk4Pm8CLbSSm75p6sJIRCeKC6TEZyZQj51ofZHLYS9jK08lFNd0RMNEzQE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619546; 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=8zQUu+TsNk2briT5cBZJ92hGKQfM61V1auBvWMi/Bjo=; b=SzvJ9OTqMUuXIK+9TpOv50lWjRvpa23ODjQgPsb5BYuIY16bKu0OvaLTSA+A6XzhaDtkxRy+fXlgA/qo9X9uA9qkWJTETM6Xho3s1TBGji6qDJwdx2bvaonQQqGYMegc1Gnl51VeKqC98wjEHCnvegenpjxoVDhPwl7uvjK2SjM= 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 1781619545995518.6719589342716; Tue, 16 Jun 2026 07:19:05 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbX-0001QC-DD; Tue, 16 Jun 2026 10:17:27 -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 1wZUbV-0001Oe-4Z for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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 1wZUbR-0003xu-V1 for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:24 -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-325-RPDHUkWuMtuTRJZr9kva0Q-1; Tue, 16 Jun 2026 10:17:19 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 4953F180034A; Tue, 16 Jun 2026 14:17:18 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id D8BD41955BC1; Tue, 16 Jun 2026 14:17:17 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 41E1321E6A02; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619440; 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=8zQUu+TsNk2briT5cBZJ92hGKQfM61V1auBvWMi/Bjo=; b=ioWnZI+IarGkp1JoRfAtopFVW7n+VxzQiAQreL7Qw4+4viz2Szfyr+5NWKr5YsKodyGmAw wR8PfwMrHjY+WiB6EeFFOd5Oo7Vpm1iplnyljmLtah+kX8lzM33A266UkGKZL+lsz7vWgy j9q656TIMI+iUyvJVQ+4sOKBnhFfeSc= X-MC-Unique: RPDHUkWuMtuTRJZr9kva0Q-1 X-Mimecast-MFC-AGG-ID: RPDHUkWuMtuTRJZr9kva0Q_1781619438 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, Filip Hejsek Subject: [PULL 01/14] qapi: drop "must exist" from ID descriptions for consistency Date: Tue, 16 Jun 2026 16:17:02 +0200 Message-ID: <20260616141715.2974467-2-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619552409158500 Content-Type: text/plain; charset="utf-8" From: Filip Hejsek Make chardev ID param descriptions more consistent with ID descriptions elsewhere. Signed-off-by: Filip Hejsek Message-ID: <20260609120221.461303-1-filip.hejsek@gmail.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/char.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/char.json b/qapi/char.json index aa5ee9ffcd..abaccefa97 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -821,7 +821,7 @@ # # Change a character device backend # -# @id: the chardev's ID, must exist +# @id: the chardev's ID # # @backend: new backend type and parameters # @@ -862,7 +862,7 @@ # # Remove a character device backend # -# @id: the chardev's ID, must exist and not be in use +# @id: the chardev's ID, must not be in use # # Since: 1.4 # @@ -879,7 +879,7 @@ # # Send a break to a character device # -# @id: the chardev's ID, must exist +# @id: the chardev's ID # # Since: 2.10 # --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619485; cv=none; d=zohomail.com; s=zohoarc; b=Zdi9+Wwsk1ttbFfMLH/F6Zk6czRGZVy01TxFNRIQ+dCRwAQamDtFtBSxFe6fsbMVTKZyGt0c904chQUqBDogaWAqFzm0JEGN9GbT581B0nEny4fDjBmAOjA4fYxZl8c8Mfo+yiYKwOWLan7W3U3AKG+5vEeSH/ICb32DIGF0yfw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619485; 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=imfkb1TdhURklEm/PqnlSD4UK086FObFpUfx+QsC6mY=; b=cI/f7lZHsNPYp1qRA1ectw+qH464GQpiWrFkkUctm2l9y8XBA5STKvV17jyv+aFO3R0PTsAECIw2auuau41vyD4yvMM69VqaQXIssxaDpWosK3dDOzaNxUM/U87UUUgXZxnMJ9zH33Fi99sOFHUEQqFynEvCD/FktqFk2rlYCoY= 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 1781619485763180.2945636184711; Tue, 16 Jun 2026 07:18:05 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbV-0001OY-0O; Tue, 16 Jun 2026 10:17:25 -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 1wZUbT-0001OI-VM for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:24 -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 1wZUbR-0003xw-UT for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:23 -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-682-wjmddUdZMH6NUIEkTqZoNQ-1; Tue, 16 Jun 2026 10:17:18 -0400 Received: from mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.95]) (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 25A211955D59 for ; Tue, 16 Jun 2026 14:17:18 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id CB30C31D2 for ; Tue, 16 Jun 2026 14:17:17 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 462CA21E6A03; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619440; 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=imfkb1TdhURklEm/PqnlSD4UK086FObFpUfx+QsC6mY=; b=DF/Wy2jYpGQOhxpBK7QLMPZXPmJp1CRpKKqjVD7noH+3r84tnKJJGTSOFMGy+jMoSptWRl +lAKKmNdeUq0IvofinBriVcHl2/TwYBZalH46E9TQWREzNMkzcZa3j34RA3fEJ8dpdZlAC d2errJ4orx1Gn51cXY/vDuTU9Ch+WO8= X-MC-Unique: wjmddUdZMH6NUIEkTqZoNQ-1 X-Mimecast-MFC-AGG-ID: wjmddUdZMH6NUIEkTqZoNQ_1781619438 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 02/14] python: temporarily restrict max mypy version Date: Tue, 16 Jun 2026 16:17:03 +0200 Message-ID: <20260616141715.2974467-3-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.6 on 10.30.177.95 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619487917158500 Content-Type: text/plain; charset="utf-8" From: John Snow The newest versions of mypy do not support targeting Python 3.9, which we still support. I want to address that soon, but in the meantime it's nice if the tests pass. Signed-off-by: John Snow Message-ID: <20260611042332.482979-2-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- python/setup.cfg | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/python/setup.cfg b/python/setup.cfg index 8097593397..ad4121a58d 100644 --- a/python/setup.cfg +++ b/python/setup.cfg @@ -40,7 +40,8 @@ devel =3D flake8 >=3D 5.0.4 fusepy >=3D 2.0.4 isort >=3D 5.6.0 - mypy >=3D 1.4.0 + # Max ver is temporary until we drop 3.9 + mypy >=3D 1.4.0, <2.0.0 pylint >=3D 2.17.3 pylint !=3D 3.2.4; python_version<"3.9" pytest >=3D 6.0.2 --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619536; cv=none; d=zohomail.com; s=zohoarc; b=CeBKHXXszyxFh70HZlVU/NU8Fzv7EAW9/XaQpTtGXKkW9wH+dwEeto8xzATJ7AVmcv45kGkukBi1oCBTh/UqntlnYxx1X13oS66s0r6s6ylB8rPPuCKuCLu6U+UEHzaHGUQYipqacf+3k6PInAA2vIorGV+FhADdgR1ojbiw2Lo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619536; 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=oXC0iO1Hz+oM+LbvcuaGj5YJhFCFriEh8sarIA2JmO8=; b=Pqo11DLSMepSVUVvDZ9QWrct3XqJaUvqCVdY9ZLzNM0hpxlM7AuMWSNTgGOTxVZjPIDFUV1Nq3zxjPcuq2onVWE2l1JlhbyhdCa5WdHPSJEFNP1/PA5tlQNnQdtQkNGy44ZJQ2sp38KmJLBdMHikOIwS28r7BZVCDiA9NNmFMOQ= 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 1781619536668848.7768463020117; Tue, 16 Jun 2026 07:18:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbW-0001PQ-Jh; Tue, 16 Jun 2026 10:17:26 -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 1wZUbV-0001Ot-KR for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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 1wZUbR-0003xv-US for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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-690-a4u5ehFUM-GmU2NoqeRSwA-1; Tue, 16 Jun 2026 10:17:19 -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 87A5519540DE for ; Tue, 16 Jun 2026 14:17:18 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F3D0518005AE for ; Tue, 16 Jun 2026 14:17:17 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4A36021E6A05; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619440; 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=oXC0iO1Hz+oM+LbvcuaGj5YJhFCFriEh8sarIA2JmO8=; b=ghfxVNTqH2gdXnh4FluXpSBXEkZhE6vMglfSLtAQTLLALUyCr05ExigyLQCzg2raRmSTTF nWVh4VhNTscKx3h4zb7MXNsr9CMV0IBP7BA92LOhD5qFSNW2hKv7usl1ZOAjv0jOyj72B8 /dJtU1ICe+nzEhbE+8xRU8S8YLQlEPM= X-MC-Unique: a4u5ehFUM-GmU2NoqeRSwA-1 X-Mimecast-MFC-AGG-ID: a4u5ehFUM-GmU2NoqeRSwA_1781619438 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 03/14] tests/qapi: generate output in source order Date: Tue, 16 Jun 2026 16:17:04 +0200 Message-ID: <20260616141715.2974467-4-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619538343158500 Content-Type: text/plain; charset="utf-8" From: John Snow 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 sections of each test documention block are printed. We now print the name of the section followed by the section text for all sections except Members and Features, which are printed as "Member=3D%s" or "Feature=3D%s" followed by the section text, respectively. 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 Message-ID: <20260611042332.482979-3-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- tests/qapi-schema/doc-good.out | 82 +++++++++++++++++----------------- tests/qapi-schema/test-qapi.py | 14 +++--- 2 files changed, 48 insertions(+), 48 deletions(-) diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 04a5507264..b9829e2f84 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 + Plain ******* Section ******* doc freeform - body=3D + Plain Just text, no heading. doc freeform - body=3D + Plain Subsection =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -106,84 +106,84 @@ Examples: - *verbatim* - {braces} doc symbol=3DEnum - body=3D + Plain =20 - arg=3Done + Member=3Done The _one_ {and only}, description on the same line - arg=3Dtwo + Member=3Dtwo =20 - feature=3Denum-feat + Feature=3Denum-feat Also _one_ {and only} - feature=3Denum-member-feat + Feature=3Denum-member-feat a member feature - section=3DPlain + Plain @two is undocumented doc symbol=3DBase - body=3D + Plain =20 - arg=3Dbase1 + Member=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 - body=3D + Plain A paragraph =20 Another paragraph =20 @var1 is undocumented - arg=3Dvar1 + Member=3Dvar1 =20 - feature=3Dvariant1-feat + Feature=3Dvariant1-feat a feature - feature=3Dmember-feat + Feature=3Dmember-feat a member feature doc symbol=3DVariant2 - body=3D + Plain =20 doc symbol=3DObject - body=3D + Plain =20 - feature=3Dunion-feat1 + Feature=3Dunion-feat1 a feature doc symbol=3DAlternate - body=3D + Plain =20 - arg=3Di + Member=3Di description starts on the same line remainder indented the same @b is undocumented - arg=3Db + Member=3Db =20 - feature=3Dalt-feat + Feature=3Dalt-feat a feature doc freeform - body=3D + Plain 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 + Plain =20 - arg=3Darg1 + Member=3Darg1 description starts on a new line, indented - arg=3Darg2 + Member=3Darg2 description starts on the same line remainder indented differently - arg=3Darg3 + Member=3Darg3 =20 - feature=3Dcmd-feat1 + Feature=3Dcmd-feat1 a feature - feature=3Dcmd-feat2 + Feature=3Dcmd-feat2 another feature - section=3DPlain + Plain .. note:: @arg3 is undocumented - section=3DReturns + Returns @Object - section=3DErrors + Errors some - section=3DTodo + Todo frobnicate - section=3DPlain + Plain .. admonition:: Notes =20 - Lorem ipsum dolor sit amet @@ -207,23 +207,23 @@ Examples:: =20 Note:: Ceci n'est pas une note - section=3DSince + Since 2.10 doc symbol=3Dcmd-boxed - body=3D + Plain If you're bored enough to read this, go see a video of boxed cats - feature=3Dcmd-feat1 + Feature=3Dcmd-feat1 a feature - feature=3Dcmd-feat2 + Feature=3Dcmd-feat2 another feature - section=3DPlain + Plain .. qmp-example:: =20 -> "this example" =20 <- ... has no title ... doc symbol=3DEVT_BOXED - body=3D + Plain =20 - feature=3Dfeat3 + Feature=3Dfeat3 a feature diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index cf7fb8a6df..5beb96e894 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,12 @@ 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 isinstance(section, QAPIDoc.ArgSection): + print(' %s=3D%s' % (section.kind, section.name)) + else: + print(' %s' % section.kind) + print(section.text) =20 =20 def open_test_result(dir_name, file_name, update): --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619544; cv=none; d=zohomail.com; s=zohoarc; b=AoUO/CchnCBaAU+qpRlBcBIei6ZFl3rJP+lMP2P4B4jwTdMu7E2cGjthvNsr0+20bC7Mq2q9j4ylZEWnwWGepe8Hpl9mrZtLLrK7VcUAVZmEauXQ6e0h8F8lCWyYLMtlQ/mQ+62l6Zi5Ssoy6wDC8xQeyYO4FUXMilFqNHyS6F0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619544; 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=x2T3mztQYd/lufHIsQaXY9sZtENNHEaIpWH9pszoZCM=; b=j5jU78VY+mg9Ja0I+l4zjE7WggVGrBKtg9kz0IEJEYyzjwlqyvAmW/2gXe13tZC7dsq0TGviEOt0lvsmt+/l3NzK4AyoPALRxTtBfFSYqYsfPZKYmBXIo9WRPQ0Xwopbr8l3FicCN9yt5LPGVN/s+0Tvu7FnoUTe8jCL8Zcpju0= 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 178161954481784.5767974626533; Tue, 16 Jun 2026 07:19:04 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbX-0001Q3-1M; Tue, 16 Jun 2026 10:17:27 -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 1wZUbV-0001Ol-DI for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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 1wZUbR-0003xx-UI for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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-314-W_Ql9GmqN-S5qtLbXIad0Q-1; Tue, 16 Jun 2026 10:17:19 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (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 56AF41955EB1 for ; Tue, 16 Jun 2026 14:17:18 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E64361954105 for ; Tue, 16 Jun 2026 14:17:17 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 4E57C21E6A07; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619440; 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=x2T3mztQYd/lufHIsQaXY9sZtENNHEaIpWH9pszoZCM=; b=Ctt0Xt7w6NA3ucNrt9XvJHoi09leHeXEz/wqH2nUbI5rWueOy7eTXHXWWEZXxZpRV9eq9q 2TI7DD4E4f3uZeuC/lahnU4qMfKEDYI2HmsbCvGnYhRkky3WXw639VzjGC/LOvw4uS3rbz fceLnlBEkszbhAOKnEjrN/0EU+TyLVA= X-MC-Unique: W_Ql9GmqN-S5qtLbXIad0Q-1 X-Mimecast-MFC-AGG-ID: W_Ql9GmqN-S5qtLbXIad0Q_1781619438 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 04/14] qapi/parser: remove unused QAPIDoc subsection members Date: Tue, 16 Jun 2026 16:17:05 +0200 Message-ID: <20260616141715.2974467-5-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619546534158500 Content-Type: text/plain; charset="utf-8" From: John Snow 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 Message-ID: <20260611042332.482979-4-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-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 c3cf33904e..b33edbba74 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 Sun Jul 26 13:29:04 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=1781619536; cv=none; d=zohomail.com; s=zohoarc; b=GdwGCrkZpY6hRV05sTNTx7EyjMXDEWgN3XxNzXzsTG3u1exUk5LewctE3Mr86l+rf2zqiDeUHfwhBXoG8sZo1+xCSjcFZcncej52n4dgUXtCTwx9CkLeT+VyfmLv9Ae/2L5TMEpxHvI6NKtNkhyQFQ1zyH/dpzGzm5Wjx/6+h2I= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619536; 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=TqZcYaO26+N2aLXux4mdqBydNRchkQMuCsd/GdcJHC4=; b=f4X+h2WR1Bw+DagpOqGG4eQt4JcPWecFHiQ/lZEVmQ4ExEBzgIz/Oe7VUE7smlT9Zbv6539NLdKiOTuoU68FqzyYSp0xBPDJYnedOjmIbAF+znFg5CXC9Oe3vaIqDKkTp7ph+8YiZwQwRxGfCM+AzELtWnMlUuyVv1yNBKVM7lM= 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 1781619536866163.6693220813553; Tue, 16 Jun 2026 07:18:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbm-0001SY-HH; Tue, 16 Jun 2026 10:17:46 -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 1wZUbV-0001P0-RR for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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 1wZUbU-0003yc-7t for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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-364-eGqKjEO7PaifmFdU1-u-NQ-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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 5DDBE195605E for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 1044E30094DD for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 523F921E6A08; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619443; 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=TqZcYaO26+N2aLXux4mdqBydNRchkQMuCsd/GdcJHC4=; b=aPYnZthdAYglH4YhRsjP0CWvfHj5aWftwsRbU+e38vTvRsHySZm7gi6YZ7XLbqtmwcdcag 6iPkQUT+j7FYkzna7Otf0Djg5zae87ZQn+X7mDn3+m7AMeVdmlSvmofADEruxIPZWGVGTR TIRS9Ykqdm5m+Mvx/broZSwZOe5Hc2M= X-MC-Unique: eGqKjEO7PaifmFdU1-u-NQ-1 X-Mimecast-MFC-AGG-ID: eGqKjEO7PaifmFdU1-u-NQ_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 05/14] qapi/parser: add has_features property Date: Tue, 16 Jun 2026 16:17:06 +0200 Message-ID: <20260616141715.2974467-6-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619538285158500 Content-Type: text/plain; charset="utf-8" From: John Snow Begin preparing to remove public access to the .features member by introducing a semantic "has features" property instead. Signed-off-by: John Snow Message-ID: <20260611042332.482979-5-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b33edbba74..dcc58170bd 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 @@ -741,6 +741,10 @@ def __init__(self, info: QAPISourceInfo, symbol: Optio= nal[str] =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') --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619502; cv=none; d=zohomail.com; s=zohoarc; b=GcZXS3cJ/YgKyD6EVDN6rX/UbPWV0Y4AfUdUdkY90Kduy/rDV/qW1oxJ+hPQrPwH6UqmNF2DumJKY8hwGdl1YRYZPyo2vMDZA3SM416vRBARhLnoAaHimdvauBbReiJ1yA6SeZmi1UERi1cqQuTMogflTE47+/HG2T5rAgOAiKU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619502; 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=hGGP8nbuBpUaZ+sPTkFOeWW7++TmBx3F5MQE/ANoCFI=; b=NcchRabpHtEEyTo8ltKXlgpTkhk1mvcl+fdvXjjD+Z54mLz1w6UGOnuoHX89zL77Bg20pWQ6EB1Q3HKVjAz3SvbRumE+FA5abuUKa/mczJXbJviiymttMKsLCw0C8y6gnH54WR/TtM+JWjh1wugkPNni0117COdV4WA8n/qcruk= 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 1781619502905483.94998400002544; Tue, 16 Jun 2026 07:18:22 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUc0-0001UA-1Y; Tue, 16 Jun 2026 10:17:57 -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 1wZUbX-0001QF-GL for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17: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 1wZUbU-0003z2-P8 for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:27 -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-209-BdrrDBKmPf6Ksu6jtnHI_A-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (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 7AE4A180044D for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E9AAF1954105 for ; Tue, 16 Jun 2026 14:17:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5620421E6A09; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619444; 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=hGGP8nbuBpUaZ+sPTkFOeWW7++TmBx3F5MQE/ANoCFI=; b=QJ3u0tsdIUoY3LonQ7o9a8Awp8GsIOqQCh9UKSoiACZDQhHRINzs3XD7ou1aCnMec6UzGp MiYbiU7A1nOGGhwU9kJSFBRZyJK7VVH2hV4KGHq3Uehw0fX3Q0b+bUOpFQXHzXixIopqKk 8Ye3wdymdgceRZtaWhSlQeCeJx7mp/s= X-MC-Unique: BdrrDBKmPf6Ksu6jtnHI_A-1 X-Mimecast-MFC-AGG-ID: BdrrDBKmPf6Ksu6jtnHI_A_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 06/14] qapi/parser: make remaining subsection members "private" Date: Tue, 16 Jun 2026 16:17:07 +0200 Message-ID: <20260616141715.2974467-7-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619504133158500 Content-Type: text/plain; charset="utf-8" From: John Snow 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 Message-ID: <20260611042332.482979-6-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 48 +++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index dcc58170bd..da4756a742 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -733,17 +733,17 @@ 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) + return bool(self._features) =20 def end(self) -> None: for section in self.all_sections: @@ -775,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( @@ -807,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, @@ -827,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 @@ -839,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 @@ -887,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: @@ -918,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 Sun Jul 26 13:29:04 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=1781619493; cv=none; d=zohomail.com; s=zohoarc; b=giHmQHxMv+xGGInTl8fZlYuy2O2z9g1/Eifa8+mpL0xwrmtoBo6WHCisXTfap3DtT9f3A/ia28pop/PWedLC+eCiIAkPwJ5MHSpCl1f0tJDkDUoVThTPn/tBpwrgCq3KY55LlsW+WUCUHlMGlgmycKlIeac+LEtslT08/WhB488= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619493; 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=xgAf7LprCisOvkKLP7QgXV90cNVvr9EwLAGYH8QQQf8=; b=TV5EgWR5isoEeGroGM6c3cG3/KX3B1EVt3aSCSM8jLsPkWYWsivA/UeuX4SNEVxOs6cPfHvN28Lpnpd/aebbNZMCoZKN8d/NpuftgGm0RSViiuaRhLcs7f1F8KQK0dRJ0GGSGamCkexYuWCu+Yb9cPqbL15cWqp/LyZjlFo1eD8= 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 1781619493070989.4190225362331; Tue, 16 Jun 2026 07:18:13 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbY-0001Qj-28; Tue, 16 Jun 2026 10:17: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 1wZUbV-0001Ou-Nm for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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 1wZUbU-0003yQ-3T for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:25 -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-464-XEisAMVrP72PrwrwQOusSw-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 40F1B1956051 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id EFB611954B08 for ; Tue, 16 Jun 2026 14:17:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5A07721E6A0A; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619443; 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=xgAf7LprCisOvkKLP7QgXV90cNVvr9EwLAGYH8QQQf8=; b=BdRpDtKGFjl7kFXvdyU3zpU2m32y8zznF5O6cMyTsaYVcXcAAxzhDke04d75wDK9i/ZzbJ eTLaHstLpMhiXF6yq5YvCQOjYycltUa5+dgmtS2sgz9u8iA2o5JweuDv9bpIykE6cev/UV ydSWx+C5EAV99ceSO9cRbUa1nMWsVBc= X-MC-Unique: XEisAMVrP72PrwrwQOusSw-1 X-Mimecast-MFC-AGG-ID: XEisAMVrP72PrwrwQOusSw_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 07/14] qapi/parser: fix comment phrasing Date: Tue, 16 Jun 2026 16:17:08 +0200 Message-ID: <20260616141715.2974467-8-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619494169158500 Content-Type: text/plain; charset="utf-8" From: John Snow Plaintext sections can be one or more paragraphs, the original comment was a mistake. Signed-off-by: John Snow Message-ID: <20260611042332.482979-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index da4756a742..d8068bb1bf 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) --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619481; cv=none; d=zohomail.com; s=zohoarc; b=HIiHQ5ZArMwU0lWMjZ5SEB90uQZ+cjcg0++pNnlLgytfaOWqX57RT1yWL/PltWw+1BdG1cdFjJs6Ai019I3oK1DcOJe85sLd8aJHdSAm8n/i7NTW06kosjvPd+4v0yjEGCD2h7vINJdABMK0640CqJxWpSmRbq4dlkHFCEIVcf0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619481; 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=OBpBjsEE2g+cwsPP1umyLpfeli8IdNVIxzIrnz1y72E=; b=ILWGKZr2QBCz0E3+o+fDqmItGLqv3ZpZRGLZACAVMtOpBgOdt1s+1NuQTcEzsgLu3tsxQ48JQy5ArxhYaGo8l3NPayDGH9RTwqRrPP03Trfzt7ucUA02MG0V8XyjnVl8CgoBhY6VFh44pVKrbrK2ao+Cx9zs6+rPv2XmWGi8vlo= 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 1781619481295965.3678850903037; Tue, 16 Jun 2026 07:18:01 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbY-0001R6-Kp; Tue, 16 Jun 2026 10:17: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 1wZUbW-0001Q1-Sq for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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 1wZUbU-0003ya-J0 for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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-511-9qprcjbpP2u9DJNpZUf3Lw-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 63D431956065 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 044D91954B09 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 5E0AB21E6A23; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619443; 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=OBpBjsEE2g+cwsPP1umyLpfeli8IdNVIxzIrnz1y72E=; b=DX8k4Tkf7CXiyRoaskEYp+6mIzhr6PNKI0WGbWus5jABHTRBTbIbgY9XEZvNYRlZTTGBoM JQCVZaIs07qxFwfgxqEcQ5Evdb1yRUJi7MJ0V1OJMemLzRKQyI/LKjBd/fEGS3YDUCD5k8 DMVeqCEt7vTPO4ulVIYyDw4IGTtCdn0= X-MC-Unique: 9qprcjbpP2u9DJNpZUf3Lw-1 X-Mimecast-MFC-AGG-ID: 9qprcjbpP2u9DJNpZUf3Lw_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 08/14] qapi: new doc comment "Intro" section Date: Tue, 16 Jun 2026 16:17:09 +0200 Message-ID: <20260616141715.2974467-9-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619484432158500 Content-Type: text/plain; charset="utf-8" From: John Snow 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 this new 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. This new section facilitates that. Signed-off-by: John Snow Message-ID: <20260611042332.482979-8-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/parser.py | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index c2f09bac16..1f7c15b707 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 d8068bb1bf..97e7dacb0f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -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 Sun Jul 26 13:29:04 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=1781619537; cv=none; d=zohomail.com; s=zohoarc; b=Hq8bIBdWa9QgM5vj+7s+M98u4adz9QCR1EYRvF4SjEbw7qitCqeconPPx7IcMTfHWerwkuZFSwngCGrWZ3rIpMPZZIOFn2wLrWGoHkWe/8UuMb+gcNcpHQDYJ6E+j97s3ivUEZCv+pV2g1uTioD37tUKmx7PxLYGyu6Y3gfFiWw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619537; 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=C1fatib0cPU30swFq4UWTmFPtrqddWj9DUB6eBOxJVw=; b=ZsFaeOkNaLWyP7O5CQfSBFT4Pjz9Y+mKnRxIxTqtYP7EV4S8DgKzS/10SbeS/kHiaDtCzHuoLAFM8aZZopD9VbyAlmEcMDSkv9nzUUGtRNEtO19kwQE9CBRP/IYLIMy3cGtV4GwugYcbuV5Jt0FQbmtU9axDP9jiv7KO4OpDqrE= 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 1781619537019739.7083275116188; Tue, 16 Jun 2026 07:18:57 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbe-0001S8-E3; Tue, 16 Jun 2026 10:17:35 -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 1wZUbX-0001QE-GF for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17: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 1wZUbU-0003yq-M2 for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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-43-wt9TrYugPEOj-i9KsIQdxw-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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 7AE7C1805C13 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 38DA93008DFF for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6207521E6A25; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619443; 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=C1fatib0cPU30swFq4UWTmFPtrqddWj9DUB6eBOxJVw=; b=fVki1dp0vW0APVm3kHv5odlYVJnrChWHgToGduEWfqJDyKoILUoQTqajy5Y8oYTdGg6W1V iq71CgZREpaztwW6NwNx4zbtUhWIN9cpRnbEM6+QUCb3/DV/67zG/V/l2VwuZrtWuhvB3E vm5zbZ8EHey7XD7rj2fokcRBK93mVOE= X-MC-Unique: wt9TrYugPEOj-i9KsIQdxw-1 X-Mimecast-MFC-AGG-ID: wt9TrYugPEOj-i9KsIQdxw_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 09/14] qapi/parser: move _insert_near_kind() method Date: Tue, 16 Jun 2026 16:17:10 +0200 Message-ID: <20260616141715.2974467-10-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619538311158500 Content-Type: text/plain; charset="utf-8" From: John Snow Move this function out from underneath `ensure_returns` and make it available for general purpose use as an object method instead. This is purely a scope-level patch with no functional changes. Signed-off-by: John Snow Message-ID: <20260611042332.482979-9-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 97e7dacb0f..261f8ba9f8 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -816,6 +816,22 @@ 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 connect_member(self, member: 'QAPISchemaMember') -> None: if member.name not in self._args: assert member.info @@ -850,28 +866,13 @@ def connect_feature(self, feature: 'QAPISchemaFeature= ') -> None: self._features[feature.name].connect(feature) =20 def ensure_returns(self, info: QAPISourceInfo) -> None: - - 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. --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619531; cv=none; d=zohomail.com; s=zohoarc; b=ajWBvjTSKgYljJmTGZ1mOatzcWc6/Ct3htRp885YxWIokZBCRowL8bO//dFsE4eKF854LUsX2dx2ubDIeBaBVy/ZY/9BxPjyTA17hbWzaTRwuL7WnV1nkexih51m52QB3FrSYBrf/vEF6lLXp1plpC2PfpI3QzzwOoQyFdK0jiE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619531; 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=oYXCCn93tfh3rX44N+JYjLiH7O+rbz5pWhaYd0EbSDw=; b=VBq8ECwjh9OrthVo3eOvRgDE9NgyR832AE2qIIb1HJnJM87MB1c65Nw5dG83ISOHGEflqHgSia11ptwB/9sZP91FBD473w3z21A5VFz95WmZUU1WsrvYRWiG825zoxk6zyw9bRv4TQCS1/o4W21vEyLmoPo/fj/bycFJLUr6MPw= 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 1781619531220795.6890630648345; Tue, 16 Jun 2026 07:18:51 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbY-0001RU-Td; Tue, 16 Jun 2026 10:17: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 1wZUbW-0001PR-IT for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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 1wZUbU-0003yy-IO for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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-364-pGJaICj7OGyQPfqBrSPBmg-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (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 8100E1955F41 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 3AFC2180058F for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 65FF221E6A26; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619444; 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=oYXCCn93tfh3rX44N+JYjLiH7O+rbz5pWhaYd0EbSDw=; b=c5CBKdm7CUkCnVnAN3OtvqLSmRIrBgZAC0AyBDqjkgWKxkg60PPRubfk37PditELhnjPlB QebjJtY5Crqta98VfzD/9sIHwAMZnvKE69r/NH47o9YS1ZSz9g06M6o1hnQwy8Or6jy9Tk 72HQbkwlQ/hVwk7xB2M5aktd2GNuFb8= X-MC-Unique: pGJaICj7OGyQPfqBrSPBmg-1 X-Mimecast-MFC-AGG-ID: pGJaICj7OGyQPfqBrSPBmg_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 10/14] qapi/parser: add mea culpa comment for ensure_returns Date: Tue, 16 Jun 2026 16:17:11 +0200 Message-ID: <20260616141715.2974467-11-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619532196158500 Content-Type: text/plain; charset="utf-8" From: John Snow These algorithms are quite a mess currently, but they are temporary until we add the inliner which will address these issues more holistically. For now, add the "mea culpa". Signed-off-by: John Snow Message-ID: <20260611042332.482979-10-jsnow@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- scripts/qapi/parser.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 261f8ba9f8..b0cead38b1 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -866,6 +866,13 @@ def connect_feature(self, feature: 'QAPISchemaFeature'= ) -> None: self._features[feature.name].connect(feature) =20 def ensure_returns(self, info: QAPISourceInfo) -> None: + # This is more complicated than it ought to be. The doc + # parser should already know where a generated RETURNS section + # should go. It currently doesn't, mostly because it accepts + # tagged sections in any order. + # + # TODO: Tighten doc syntax and simplify. + if any(s.kind =3D=3D QAPIDoc.Kind.RETURNS for s in self.all_sectio= ns): return =20 --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619481; cv=none; d=zohomail.com; s=zohoarc; b=LYk0zSFL+2kH4bABVJ3jarl2XGbNk1gSBKTRq8A7ia/kgxMOo+bWbHN3I/vJBlPDLK/OmbcTZLz7v7cbRp9HHojpGjhV5qlfz22roWqf6EhSmc6NddwOcZNeMalRoow+8WTh7s1B4kxoZFQBkknWzTpgbknxY6AcO/xmor+pKOU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619481; 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=CpCUiwowvqqxMHi30Rr8I+oiVbpGueGWYF0ytoPZwC0=; b=NB5IN4MQavpTigWKm338MH6kt1RSK2pEnDccZ09gPKlFhW1SjEoJSAjtYq5rQz1my3Ugd6t4inf75v4617epD9P4vO+AoizTzYn92wUud0KhoSzCAX64bdGBkoo3NxCCCjGhEoXccptkzD/JV050VdnzIznQXHaGQ7pFlI4YMY0= 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 1781619481358709.4614935107041; Tue, 16 Jun 2026 07:18:01 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbd-0001Rx-6m; Tue, 16 Jun 2026 10:17: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 1wZUbY-0001R0-FW for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:28 -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 1wZUbU-0003z1-P9 for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:28 -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-209-2xCSJuDUOEe57K2O84gFuA-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (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 765341956068 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DEC723008DFE for ; Tue, 16 Jun 2026 14:17:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6A31321E6A35; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619444; 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=CpCUiwowvqqxMHi30Rr8I+oiVbpGueGWYF0ytoPZwC0=; b=TRCzBbrtbFdvS0SEwGAjN1IERiSqYerepU8umhH1AIe+AJ2MTBnhM3PrFQhfLrIP7/Sivg PdA6Ae/Id9JqfSF07NKNXUJjSLMsprIV4Kgx7FUFOQM3M+xwpShf0lFmOgUYdgemC8oQoX mQMTz1n8ioE3Dc//SPFzfOJ9mNCjrAU= X-MC-Unique: 2xCSJuDUOEe57K2O84gFuA-1 X-Mimecast-MFC-AGG-ID: 2xCSJuDUOEe57K2O84gFuA_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 11/14] qapi: adjust doc comment stub member insertion algorithm Date: Tue, 16 Jun 2026 16:17:12 +0200 Message-ID: <20260616141715.2974467-12-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619484514158500 Content-Type: text/plain; charset="utf-8" From: John Snow 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. This will affect the code that inserts "Not documented" descriptions for undocumented members ("stub sections") and the dummy section that marks the spot for "The members of ..." references. Adjust the algorithm to cope with not only the finished state, but temporary intermediate states while the series is merged. This algorithm can handle zero-or-more PLAIN *or* INTRO sections at the beginning of a QAPIDoc object, in contrast to the previous algorithm which assumed and relied upon there being always one PLAIN section at the beginning of every QAPIDoc section list. In other words: (PLAIN | INTRO)* This does not impact what the parser itself will actually produce. As of this patch, the parser will still always generate QAPIDoc section lists that start with precisely one PLAIN section (whether or not it is empty), followed by the remaining sections. Those remaining sections may or may not include additional PLAIN sections, but never two such sections contiguously as the parser will always treat that layout as one PLAIN section consisting of multiple paragraph(s). In other other words: This insertion algorithm is more lenient than the parser, but this is on purpose for flexibility mid-stream as we convert QAPI to using explicit introductory sections. The allowed order of sections will eventually become strictly enforced in the parser, which will in turn allow dramatic simplifications to the insertion algorithm. This only exists as transitory code until we are able to enforce that order. Fear not: the intermediate ReST output before and after this patch are byte identical, so failing all else, we at least know it doesn't make anything worse. Lastly, because we have three places in the code that need to insert stub/dummy sections, we take the opportunity to consolidate this code to handle all three cases with one function. This winds up necessitating the qapidoc.py generator actually modify the section list to insert a "dummy" member that acts as a placeholder for "The members of ..." text. While it looks like a code smell to modify the caller's argument, it is ultimately safe because the QAPI Schema object is re-parsed and re-constructed in memory for each individual process that needs to operate on it. In other words, the Sphinx document generator already does have "its own copy" of the section lists, so it is "safe" to modify here without regards to other consumers of the QAPIDoc objects. It only *looks* like it smells bad. Ultimately, this code will also be removed once the inliner is merged, so it is only a temporary aesthetic issue regardless. That's my story and I'm sticking to it. Signed-off-by: John Snow Message-ID: <20260611042332.482979-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 42 ++++++++++++++++-------------- scripts/qapi/parser.py | 58 +++++++++++++++++++++++++++++------------- 2 files changed, 64 insertions(+), 36 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 1f7c15b707..16ad15fe94 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -349,30 +349,38 @@ def _get_target( ) =20 def visit_sections(self, ent: QAPISchemaDefinition) -> None: + # Generate a placeholder right after the member section(s) which + # may be used to generate documentation for "The members of..." + # pointers in the rendered document. + # + # This is a temporary hack until the inliner is merged. Note + # that although we modify the caller's section list, the + # Sphinx document generator has its own copy of the parsed + # schema in memory, so this action does not interfere with + # other users of the QAPISchema or QAPIDoc objects outside of + # the document generator. Fishy, but not harmful. + 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 +394,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 b0cead38b1..09720a2c27 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -832,6 +832,42 @@ def _insert_near_kind( return True return False =20 + 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 @@ -841,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 @@ -889,10 +915,8 @@ def ensure_returns(self, info: QAPISourceInfo) -> None: )): 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 Sun Jul 26 13:29:04 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=1781619537; cv=none; d=zohomail.com; s=zohoarc; b=ARbk01U90nAOk2way3Xmx3AL91pm28YHSoixnqoTxLDPPIAei3lXXtXtOehGiafeEwajqWXOq4w2uE71OK1Qf8oBdls+04axBrjTVG1s8P2ymOxbgz4sNd36X+zlS78jH2xw330krzr39AW0l7Sg3fcc4aJZVL0SmwAYdl1yBBw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619537; 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=FFBl/N/U5ONcQNOCiC7Th4dffQSPKPn7UX5JIC8u6kg=; b=NypqPqoijtKuN7j9oSj7pSVAy1/n78sLu+AhuXri3O7BNWhQvydhXz7LMaaGSIqeW6yUPYDVzyfAUH/siPYtzgmd7ccVIi7RyCdYMdzayUqeztf78ZIRxLGWt5QozezYq16CQ4CQru00uubQC7Vhk8oqAkOPnnAWQSKQSLpJCWM= 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 1781619537762102.28073655007245; Tue, 16 Jun 2026 07:18:57 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUbq-0001TD-F3; Tue, 16 Jun 2026 10:17:46 -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 1wZUbW-0001PP-Hu for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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 1wZUbU-0003yh-Fk for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:26 -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-711-P5WZDWdNP8OzVi3n_lVmYA-1; Tue, 16 Jun 2026 10:17:22 -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 2208619539A7 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id C4F3918005AE for ; Tue, 16 Jun 2026 14:17:20 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 6E30421E6A36; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619443; 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=FFBl/N/U5ONcQNOCiC7Th4dffQSPKPn7UX5JIC8u6kg=; b=eRKPaohgXfWTQ13wNMuh/sBYTc/LfU7H8tFlLiIb8N/oweT3fVMdZDfmE8uqIfXksp0rZl 56PEwm2V/jgKB3VBmrD7BRQmHCynU1AA79llRPjSjgI3NIUlyjeAq7pvSywy/HKBieLYuH Pu0e/cbfTzHSVKT6RHq2cMtF0lY24SM= X-MC-Unique: P5WZDWdNP8OzVi3n_lVmYA-1 X-Mimecast-MFC-AGG-ID: P5WZDWdNP8OzVi3n_lVmYA_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 12/14] qapi: remove implicit doc comment Plain section Date: Tue, 16 Jun 2026 16:17:13 +0200 Message-ID: <20260616141715.2974467-13-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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_H3=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: 1781619538298158500 Content-Type: text/plain; charset="utf-8" From: John Snow Prior to this patch, we always create 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 Message-ID: <20260611042332.482979-12-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- 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 09720a2c27..b7a7b9465a 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 b9829e2f84..16f4422177 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 - Plain - Member=3Done The _one_ {and only}, description on the same line Member=3Dtwo @@ -119,8 +117,6 @@ a member feature Plain @two is undocumented doc symbol=3DBase - Plain - Member=3Dbase1 description starts on a new line, minimally indented @@ -138,16 +134,10 @@ a feature Feature=3Dmember-feat a member feature doc symbol=3DVariant2 - Plain - doc symbol=3DObject - Plain - Feature=3Dunion-feat1 a feature doc symbol=3DAlternate - Plain - Member=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 - Plain - Member=3Darg1 description starts on a new line, indented @@ -223,7 +211,5 @@ another feature =20 <- ... has no title ... doc symbol=3DEVT_BOXED - Plain - Feature=3Dfeat3 a feature --=20 2.54.0 From nobody Sun Jul 26 13:29:04 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=1781619535; cv=none; d=zohomail.com; s=zohoarc; b=mv8uXGFC+jOWNOCZ2Q1qfJZ3fTPqMCQ9l27VvZbvgWs1VDI18G3SMr2nRJ00NFBa5aDBxBbQkAUJKyo/A/N9Jmi9yXT1+QFfJ59Pijlrmmx7qzckepm9n/fFZZZ2TWXWEY+TRFkNXmuNYEZEMV5/VvA9O9iRNWa7xbijTpkIukA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619535; 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=UGWl+eWBGT0ilNOB7AK33+tjoJBkKk5XAmTAlAdKWtY=; b=g/G6pgQYmLG7KOucV7vVZqNn76L5uHwFD6O3yhULu2+HMHeYLkf7VPy10O7d2sntv+Wo75AK/3HEzwt9icgVrvAPLU1JTm0j2AamgtD143gHiK/btyBbZSVNdew31T/9GABO6OkmBjeoewvJblOK4zx7PKXFmcTGYk4MxyRMbtI= 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 17816195355241019.8760087001136; Tue, 16 Jun 2026 07:18:55 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUcC-0001bE-0M; Tue, 16 Jun 2026 10:18:08 -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 1wZUbY-0001Qr-6E for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:28 -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 1wZUbW-0003zh-AI for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:27 -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-466-GFxRyHGUNwuT4HG1rHJvOA-1; Tue, 16 Jun 2026 10:17:23 -0400 Received: from mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.95]) (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 967A01805C26 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 5198E31D2 for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 722D521E6A37; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619445; 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=UGWl+eWBGT0ilNOB7AK33+tjoJBkKk5XAmTAlAdKWtY=; b=KQhYCWDQGplNwgTmBmCUpr9iU8QP9LvWzCOfa/21wqkvBbLTkN8h9Cn1lUBfR6jt7Br/nA n/qpS3T1oVEYVlQIW4eIy6q9iqQktCYo67xMhJCljiLYUnBo9S9y/XaWCkoKoNfb1zTrJ5 bMQoRS05iktyPLxDsADW13yGykMZD4g= X-MC-Unique: GFxRyHGUNwuT4HG1rHJvOA-1 X-Mimecast-MFC-AGG-ID: GFxRyHGUNwuT4HG1rHJvOA_1781619441 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 13/14] qapi/qapidoc: add rendering for INTRO sections Date: Tue, 16 Jun 2026 16:17:14 +0200 Message-ID: <20260616141715.2974467-14-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.6 on 10.30.177.95 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -24 X-Spam_score: -2.5 X-Spam_bar: -- X-Spam_report: (-2.5 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619536260158500 Content-Type: text/plain; charset="utf-8" From: John Snow Amend the qapidoc generator to handle and render INTRO sections. The only real difference here from other sections is that we need to dedent the text so it renders correctly. Members and Features are also indented, but do not require a dedent() because they are always used in tandem with an rST construct that forms the start of a new indented block; there is coincidental harmony. Plaintext sections, however, do not start their own block and thus need to be dedented to prevent accidentally rendering them as a blockquote or a syntax error. This dedent transformation on the text does not reflow the text, so source line information remains accurate, and the "blame" chain of custody for sphinx rST parsing error messages continues to be correct even through this transformation. Signed-off-by: John Snow Message-ID: <20260611042332.482979-13-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 16ad15fe94..54a32e45f7 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,15 @@ def add_lines( self, content: str, info: QAPISourceInfo, + dedent: bool =3D False, ) -> None: lines =3D content.splitlines(True) + + if dedent: + lines =3D textwrap.dedent(content).splitlines(True) + else: + lines =3D content.splitlines(True) + for i, line in enumerate(lines): self.add_line_raw(line, info.fname, info.line + i) =20 @@ -223,13 +231,16 @@ def reformat_arobase(text: str) -> str: =20 # Transmogrification helpers =20 - def visit_paragraph(self, section: QAPIDoc.Section) -> None: + def visit_plaintext(self, section: QAPIDoc.Section) -> None: # Squelch empty paragraphs. if not section.text: return =20 + # Intro sections, which are indented in QAPI source, need to + # be dedented to avoid accidental block quotes in ReST syntax. + 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: @@ -373,7 +384,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_plaintext(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 Sun Jul 26 13:29:04 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=1781619536; cv=none; d=zohomail.com; s=zohoarc; b=GDNPoc4aSPpoz6jOUpEO5/EFehDnUCtXzI+6UqXnuqUu3+JzJTm71w5qz2crZfm0G/viR18HZkE0kIYM1jXOv1InkNlH8KRhZs6b4HehptvtqsdBXhWSr28j5/KoSd8wEw53erJz1BjjCHbJQYJlztknRp01YY0a58WVvfD94xc= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1781619536; 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=98qCAa40b2WRoqkSDRJEiAfNrGQZ3fKQ3kKQj22kUvY=; b=mxVd92MUGeh+kmOmtMjQ9SCzUPWCfcSpVW4fDPqVkzQciNB9Sic4Sdczhh6bFM0z8WV4OKlwKC2FG0UfzvmrZZQF42sKH2YZfQC/QA/xFwa/op1+zdaYyOYRHYlO2ObeGkM3FYyhEBVhkEmT1TjauXuGptd7XdNnLP5hEW/UYlY= 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 1781619536204513.3474870973141; Tue, 16 Jun 2026 07:18:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists1p.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1wZUc2-0001UV-Nu; Tue, 16 Jun 2026 10:18:00 -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 1wZUbX-0001Qi-Uw for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:27 -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 1wZUbV-0003zI-SU for qemu-devel@nongnu.org; Tue, 16 Jun 2026 10:17:27 -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-398-CX6qRwv9Pr2rgH5QU4pe9w-1; Tue, 16 Jun 2026 10:17:22 -0400 Received: from mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.95]) (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 06FC21955F56 for ; Tue, 16 Jun 2026 14:17:22 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.44.22.4]) by mx-prod-int-10.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 74860364CC for ; Tue, 16 Jun 2026 14:17:21 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 7624621E6A3C; Tue, 16 Jun 2026 16:17:15 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1781619444; 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=98qCAa40b2WRoqkSDRJEiAfNrGQZ3fKQ3kKQj22kUvY=; b=HJeWWGHYL1snDlmqzwgZ0+oGXNtUVPS99wKEa45ntoac86e5WrLe7k2sddRijAzmGpXlDU KGN/1NBHvcZY/ICnXlJeaYgxnfrfVTcXxL7NqAEcmbu+EBhofsgF/XMs8mIFAX4xjb6ps3 PPvzYrCQa6uG/RV3jEoUQN+suz8iUL8= X-MC-Unique: CX6qRwv9Pr2rgH5QU4pe9w-1 X-Mimecast-MFC-AGG-ID: CX6qRwv9Pr2rgH5QU4pe9w_1781619442 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 14/14] qapi: add doc comment "Intro" section parsing Date: Tue, 16 Jun 2026 16:17:15 +0200 Message-ID: <20260616141715.2974467-15-armbru@redhat.com> In-Reply-To: <20260616141715.2974467-1-armbru@redhat.com> References: <20260616141715.2974467-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.6 on 10.30.177.95 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 8 X-Spam_score: 0.8 X-Spam_bar: / X-Spam_report: (0.8 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.445, 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: 1781619538332158500 Content-Type: text/plain; charset="utf-8" From: John Snow Add parsing for explicit Intro section syntax. A side effect of this patch is that we will (currently) 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 Message-ID: <20260611042332.482979-14-jsnow@redhat.com> Reviewed-by: Markus Armbruster [Commit message tweaked] Signed-off-by: Markus Armbruster --- docs/devel/qapi-code-gen.rst | 16 +++++++--------- scripts/qapi/parser.py | 4 ++-- tests/qapi-schema/doc-good.out | 18 ++++++++++++++++++ 3 files changed, 27 insertions(+), 11 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 3a632b4a64..b1cc5b5f0d 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -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 indented 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:: @@ -1093,8 +1093,7 @@ Examples of complete definition documentation:: =20 ## # @BlockStats: - # - # Statistics of a virtual block device or a block backing device. + # Statistics of a virtual block device or a block backing device. # # @device: If the stats are for a virtual block device, the name # corresponding to the virtual block device. @@ -1111,8 +1110,7 @@ Examples of complete definition documentation:: =20 ## # @query-blockstats: - # - # Query the @BlockStats for all virtual block devices. + # Query the @BlockStats for all virtual block devices. # # @query-nodes: If true, the command will query all the block nodes # ... explain, explain ... diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b7a7b9465a..9e14c2f792 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -542,8 +542,8 @@ def get_doc(self) -> 'QAPIDoc': if not symbol: raise QAPIParseError(self, "name required after '@'") doc =3D QAPIDoc(info, symbol) - self.accept(False) - line =3D self.get_doc_line() + doc.all_sections.append(QAPIDoc.Section(info, QAPIDoc.Kind.INT= RO)) + line =3D self.get_doc_indented(doc) no_more_args =3D False =20 while line is not None: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 16f4422177..371dd25ffc 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 + Intro + Member=3Done The _one_ {and only}, description on the same line Member=3Dtwo @@ -117,10 +119,14 @@ a member feature Plain @two is undocumented doc symbol=3DBase + Intro + Member=3Dbase1 description starts on a new line, minimally indented doc symbol=3DVariant1 + Intro + Plain A paragraph =20 @@ -134,10 +140,16 @@ a feature Feature=3Dmember-feat a member feature doc symbol=3DVariant2 + Intro + doc symbol=3DObject + Intro + Feature=3Dunion-feat1 a feature doc symbol=3DAlternate + Intro + Member=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 + Intro + Member=3Darg1 description starts on a new line, indented @@ -198,6 +212,8 @@ Note:: Since 2.10 doc symbol=3Dcmd-boxed + Intro + Plain 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 + Intro + Feature=3Dfeat3 a feature --=20 2.54.0