From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724125; cv=none; d=zohomail.com; s=zohoarc; b=cMQd3tAuKXGZyDYZ0BnBB2qB3t7yVjX8onX2OhtYYgs0tA8emV8Ny2g+pLDKkG0ua9801IqR6MRReUfPKzWHTHZBL3lS5Rl9ba54DM/bsMZPRN0sxhnl9gbPj4aseKU+86rJkS424kdvrdY5gxd1Lzaa6YCyiXY9Duz4ofiEcrg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724125; 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=+RzftgnLBNVr6C43H4A1QzDv5Zs9VxuLj2lXPY5842U=; b=BdNGWwrYub4V+uHWf0Ej7KLR5r9UPfca3fHMBCJDucIai2hDRpfvoXXQVo0satEd7okRy1trlTvUYKTXg9KX+YU2k42dPWkLej96uLtfQ74sDj8vHEaYdNgCOrSOd/tEffg84qOIg1qOFlvBdYLnn+MvKIUcUOSDdOZ6UyhGD78= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724125012545.2123126108759; Tue, 14 May 2024 15:02:05 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s709x-0005Xx-Db; Tue, 14 May 2024 17:58:09 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709u-0005Wt-BN for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:06 -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 1s709s-0008QD-74 for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:06 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-12-y3q4g-eMPqmS-ECOlYuzzw-1; Tue, 14 May 2024 17:57:49 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 46DE13806704; Tue, 14 May 2024 21:57:48 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 60F806BC5; Tue, 14 May 2024 21:57:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723883; 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=+RzftgnLBNVr6C43H4A1QzDv5Zs9VxuLj2lXPY5842U=; b=ej+3XC57GK0LrRjHj4ZyDEiEz0QxG50ZtnVI0Ux93rnAGRHnpBEeD+T8rdQUF1PM3yVb6c yRMM58SZDJbNHROWRGxpqPL4wtl0x4pD1r5lZzgP403nxwFgaOMajzZUIcI+ZEvWZJg+Jw ZAhQ0Vz8t/CQLM5hWGXQxKP+oYXVZJw= X-MC-Unique: y3q4g-eMPqmS-ECOlYuzzw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 01/20] [DO-NOT-MERGE]: Add some ad-hoc linting helpers. Date: Tue, 14 May 2024 17:57:20 -0400 Message-ID: <20240514215740.940155-2-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724127120100003 Content-Type: text/plain; charset="utf-8" These aren't ready for upstream inclusion, because they do not properly manage version dependencies, execution environment and so on. These are just the tools I use in my Own Special Environment :tm: for testing and debugging. They've been tested only on Fedora 38 for right now, which means: Python 3.11.4-1.fc38 pylint 2.17.4-2.fc38 mypy 1.4.0-1.fc38 isort 5.12.0-1.fc38 flake8 5.0.3-2.fc38 "Soon" :tm: I'll move the qapi generator code under the python/ directory to take advantage of the more robust linting infrastructure there, but that's going to happen after this series. Sorry about that! Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi-lint.sh | 51 +++++++++++++++++++++++++++++++++++++++++++ scripts/qapi/Makefile | 5 +++++ 2 files changed, 56 insertions(+) create mode 100755 scripts/qapi-lint.sh create mode 100644 scripts/qapi/Makefile diff --git a/scripts/qapi-lint.sh b/scripts/qapi-lint.sh new file mode 100755 index 00000000000..528b31627eb --- /dev/null +++ b/scripts/qapi-lint.sh @@ -0,0 +1,51 @@ +#!/usr/bin/env bash +set -e + +if [[ -f qapi/.flake8 ]]; then + echo "flake8 --config=3Dqapi/.flake8 qapi/" + flake8 --config=3Dqapi/.flake8 qapi/ +fi +if [[ -f qapi/pylintrc ]]; then + echo "pylint --rcfile=3Dqapi/pylintrc qapi/" + pylint --rcfile=3Dqapi/pylintrc qapi/ +fi +if [[ -f qapi/mypy.ini ]]; then + echo "mypy --config-file=3Dqapi/mypy.ini qapi/" + mypy --config-file=3Dqapi/mypy.ini qapi/ +fi + +if [[ -f qapi/.isort.cfg ]]; then + pushd qapi + echo "isort -c ." + isort -c . + popd +fi + +if [[ -f ../docs/sphinx/qapi-domain.py ]]; then + pushd ../docs/sphinx + + echo "mypy --strict qapi-domain.py" + mypy --strict qapi-domain.py + echo "flake8 qapi-domain.py --max-line-length=3D99" + flake8 qapi-domain.py --max-line-length=3D99 + echo "isort qapi-domain.py" + isort qapi-domain.py + echo "black --check qapi-domain.py" + black --check qapi-domain.py + + echo "flake8 qapidoc.py --max-line-length=3D99" + flake8 qapidoc.py --max-line-length=3D99 + echo "isort qapidoc.py" + isort qapidoc.py + echo "black --check qapidoc.py" + black --check qapidoc.py + + popd +fi + +pushd ../build +make -j13 +make check-qapi-schema +make docs +make sphinxdocs +popd diff --git a/scripts/qapi/Makefile b/scripts/qapi/Makefile new file mode 100644 index 00000000000..314e8a5505e --- /dev/null +++ b/scripts/qapi/Makefile @@ -0,0 +1,5 @@ +check: + isort -c . + flake8 . + cd .. && pylint --rcfile=3Dqapi/pylintrc qapi + cd .. && mypy -p qapi --config-file=3Dqapi/mypy.ini --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724074; cv=none; d=zohomail.com; s=zohoarc; b=LWOEKCloUSuYVivtR2vKVOKVMV0Mtr4qR4xo7R12q8JijjQxUnWip+ccM6y4DYZjjsWDIePGseOt+O2yHJYaZczJMpQ7Ee1DEy/i47cmBJ+6kGk3b7OiQZSCGYPHjKuYt/xW3s4L9o6GohLcW1iSDN1kV5zu2opDS0UaL/UjsQ8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724074; 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=0ouoax/E/gbtdZvx7I74VapvusDZQ7GU2MbbNnh5EzA=; b=KqpL1SxG6OiLpOPUXoKGyZ6z6G4y+D/fnaLKsUoRT6sW0BeVOcBiPiL7r0hb79TWRw5viJEukA+q7Fqi+iA3uDDc+61Matq6gcjO3hze6A955ieJbi8XEO1oRItOfDVpQvfRQCB28dosSZobrjR5tndPB56TWiFsLHpsNFSg7ic= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724074496209.7018206179148; Tue, 14 May 2024 15:01:14 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s709w-0005Xc-0H; Tue, 14 May 2024 17:58:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709l-0005Ui-Pn for qemu-devel@nongnu.org; Tue, 14 May 2024 17:57:59 -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 1s709j-0008OO-Dt for qemu-devel@nongnu.org; Tue, 14 May 2024 17:57:56 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-569-VfTYw1xAPWeGVOYHgs-qqw-1; Tue, 14 May 2024 17:57:52 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 3B39C8029E2; Tue, 14 May 2024 21:57:51 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 576476BC0; Tue, 14 May 2024 21:57:48 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723874; 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=0ouoax/E/gbtdZvx7I74VapvusDZQ7GU2MbbNnh5EzA=; b=HIi4rerF0ybvv+cxDagwpLQVUqXpuwwGpa+lW89lcLVW3G4uhNWnQJzPXV4u/2E8N+7PYC YB+CuRCU86te01rMAPfDgUR6uwD/rMB2nR+fPOf9s9FYdwNXwSDdv2BAtw/7Wb1ExhT9v2 Wesy62qT1oFqJMhNVP2Ue68uaKDR5Ls= X-MC-Unique: VfTYw1xAPWeGVOYHgs-qqw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 02/20] qapi: linter fixups Date: Tue, 14 May 2024 17:57:21 -0400 Message-ID: <20240514215740.940155-3-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724074960100001 Content-Type: text/plain; charset="utf-8" Fix minor irritants to pylint/flake8 et al. (Yes, these need to be guarded by the Python tests. That's a work in progress, a series that's quite likely to follow once I finish this Sphinx project. Please pardon the temporary irritation.) Signed-off-by: John Snow Acked-by: Stefan Hajnoczi Reviewed-by: Markus Armbruster --- scripts/qapi/introspect.py | 8 ++++---- scripts/qapi/schema.py | 6 +++--- scripts/qapi/visit.py | 5 +++-- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py index 86c075a6ad2..ac14b20f308 100644 --- a/scripts/qapi/introspect.py +++ b/scripts/qapi/introspect.py @@ -27,8 +27,8 @@ from .schema import ( QAPISchema, QAPISchemaAlternatives, - QAPISchemaBranches, QAPISchemaArrayType, + QAPISchemaBranches, QAPISchemaBuiltinType, QAPISchemaEntity, QAPISchemaEnumMember, @@ -233,9 +233,9 @@ def _use_type(self, typ: QAPISchemaType) -> str: typ =3D type_int elif (isinstance(typ, QAPISchemaArrayType) and typ.element_type.json_type() =3D=3D 'int'): - type_intList =3D self._schema.lookup_type('intList') - assert type_intList - typ =3D type_intList + type_intlist =3D self._schema.lookup_type('intList') + assert type_intlist + typ =3D type_intlist # Add type to work queue if new if typ not in self._used_types: self._used_types.append(typ) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index 721c470d2b8..d65c35f6ee6 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -730,6 +730,7 @@ def set_defined_in(self, name: str) -> None: for v in self.variants: v.set_defined_in(name) =20 + # pylint: disable=3Dunused-argument def check( self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember] ) -> None: @@ -1166,7 +1167,7 @@ def _def_definition(self, defn: QAPISchemaDefinition)= -> None: defn.info, "%s is already defined" % other_defn.describe()) self._entity_dict[defn.name] =3D defn =20 - def lookup_entity(self,name: str) -> Optional[QAPISchemaEntity]: + def lookup_entity(self, name: str) -> Optional[QAPISchemaEntity]: return self._entity_dict.get(name) =20 def lookup_type(self, name: str) -> Optional[QAPISchemaType]: @@ -1302,11 +1303,10 @@ def _make_implicit_object_type( name =3D 'q_obj_%s-%s' % (name, role) typ =3D self.lookup_entity(name) if typ: - assert(isinstance(typ, QAPISchemaObjectType)) + assert isinstance(typ, QAPISchemaObjectType) # The implicit object type has multiple users. This can # only be a duplicate definition, which will be flagged # later. - pass else: self._def_definition(QAPISchemaObjectType( name, info, None, ifcond, None, None, members, None)) diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py index e766acaac92..12f92e429f6 100644 --- a/scripts/qapi/visit.py +++ b/scripts/qapi/visit.py @@ -280,8 +280,9 @@ def gen_visit_alternate(name: str, abort(); default: assert(visit_is_input(v)); - error_setg(errp, "Invalid parameter type for '%%s', expected: %(na= me)s", - name ? name : "null"); + error_setg(errp, + "Invalid parameter type for '%%s', expected: %(name)s", + name ? name : "null"); /* Avoid passing invalid *obj to qapi_free_%(c_name)s() */ g_free(*obj); *obj =3D NULL; --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715723930; cv=none; d=zohomail.com; s=zohoarc; b=fFjPTddeqXCubPtlhgVXMTpiLwXLUzqiWHVUdabUIqj2GG/tldlMChRU87Enkfrv6R6f2i8Sr2k+dCZOuSlyVwoXrFSTftMkYJAWaB9+jIZNQ48sVd0lZ014/mJi0p+R2UamQsSGlqd6fKDausM3P5jvNYjW4QF5laPbTHZ+T6k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715723930; 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=kcmerUNUa2TkCvVPBaPfOryjLeuh/pwfq97sjE6C5PM=; b=do9WFf/Is2qckOaMZ8fwQxRbEjmtv5QBbryQZKXVnfa9olHOdCVD7yOYklkqofBdIYM4Z5A1cm7BlVJ7Mj1NpyIvczZ+ixyZS83qwIylZQ9n+c81mahiGmLQ+BtuFRV5E4bBmpM18HRs3qa3FWjb55YZmMxv+g/Ty2BWBzt5MGQ= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715723930050877.5807663940097; Tue, 14 May 2024 14:58:50 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s709u-0005Wl-SW; Tue, 14 May 2024 17:58:07 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709o-0005VF-Pg for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:01 -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 1s709n-0008P8-6L for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:00 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-478-Y9E1L4InOzK5oGzMCUw_7w-1; Tue, 14 May 2024 17:57:55 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 95F1629ABA0B; Tue, 14 May 2024 21:57:54 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 4CD656BC5; Tue, 14 May 2024 21:57:51 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723878; 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=kcmerUNUa2TkCvVPBaPfOryjLeuh/pwfq97sjE6C5PM=; b=HoMHdmJbEC7qPqHccLzIKBD7+V9tADb/dk6jkzxZUruJFRr39Xdk889Sep+kXIkIDHyEjE pkqCdkEoXq9mP8l96NcV4YpRB2rcCef7gIbulfYPlZ+lhrLdKGjNghLlH67xxfY0VgvOBK cdasDEX736pM890aTp+pfcIsKUnNipg= X-MC-Unique: Y9E1L4InOzK5oGzMCUw_7w-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 03/20] docs/qapidoc: delint a tiny portion of the module Date: Tue, 14 May 2024 17:57:22 -0400 Message-ID: <20240514215740.940155-4-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715723932458100003 Content-Type: text/plain; charset="utf-8" In the coming patches, it's helpful to have a linting baseline. However, there's no need to shuffle around the deck chairs too much, because most of this code will be removed once the new qapidoc generator (the "transmogrifier") is in place. To ease my pain: just turn off the black auto-formatter for most, but not all, of qapidoc.py. This will help ensure that *new* code follows a coding standard without bothering too much with cleaning up the existing code. For manual checking for now, try "black --check qapidoc.py" from the docs/sphinx directory. "pip install black" (without root permissions) if you do not have it installed otherwise. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi Reviewed-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f270b494f01..1655682d4c7 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -28,28 +28,30 @@ import re =20 from docutils import nodes +from docutils.parsers.rst import Directive, directives from docutils.statemachine import ViewList -from docutils.parsers.rst import directives, Directive -from sphinx.errors import ExtensionError -from sphinx.util.nodes import nested_parse_with_titles -import sphinx -from qapi.gen import QAPISchemaVisitor from qapi.error import QAPIError, QAPISemError +from qapi.gen import QAPISchemaVisitor from qapi.schema import QAPISchema =20 +import sphinx +from sphinx.errors import ExtensionError +from sphinx.util.nodes import nested_parse_with_titles + =20 # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later # use switch_source_input. Check borrowed from kerneldoc.py. -Use_SSI =3D sphinx.__version__[:3] >=3D '1.7' +Use_SSI =3D sphinx.__version__[:3] >=3D "1.7" if Use_SSI: from sphinx.util.docutils import switch_source_input else: from sphinx.ext.autodoc import AutodocReporter =20 =20 -__version__ =3D '1.0' +__version__ =3D "1.0" =20 =20 +# fmt: off # Function borrowed from pydash, which is under the MIT license def intersperse(iterable, separator): """Yield the members of *iterable* interspersed with *separator*.""" --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724081; cv=none; d=zohomail.com; s=zohoarc; b=lvgTkSBSWFVw0/TygKKtq3CjTZ5H+PnauYeLZxMOofKHI2s/KoXnJ/455X+8+U8ylX+pkwpCu4g5P5f37z6EcyjSs0RjrRp+sXeF6whu6MX/Ric7xNK9lmRK3rZgjktK4juOFtbbwPzYAIG8GlXfoyN0VKTYBeJOQnvV8NNUJJM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724081; 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=7/DfOPlH5gs0diXQtgz3pXaLIlH4rV8K/i8zUNxA/3Q=; b=gTHBO0Z0m8+SDHl3wCcXvxp6IF4kCkyQ9rz/PpvROJuic1AAd6xg4ly3wyeSpWbZEfReH5Ay+d0bIGuu926XEqgsXJ5zbNDu5Uboi0ljbntbt65h1qfJLwH0w6Rs5wYTYtJV361gNjqd9jQm0Syc7/zfS0hhCEVuJNcKY1hkWBI= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724081826802.2744733176834; Tue, 14 May 2024 15:01:21 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s709w-0005Xg-8v; Tue, 14 May 2024 17:58:08 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709s-0005WK-Tg for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:05 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709p-0008Pj-Tu for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:04 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-20-Ot5wjhPmNbaPm-mGJu2axA-1; Tue, 14 May 2024 17:57:58 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 90DC63801EDA; Tue, 14 May 2024 21:57:57 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id AD6FB3C27; Tue, 14 May 2024 21:57:54 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723881; 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=7/DfOPlH5gs0diXQtgz3pXaLIlH4rV8K/i8zUNxA/3Q=; b=JxVlKQFZjRCpIKNOBMX2DlrzSNq89Qlb/JYz61raYkmmd9qRbh5gfpI3UtLuFvGOL42s7g MxWIV7oRbAW/Oebr13Cow86/+eXmfBPzCp9Xbs4e86OXITofiLka4W5H4qi7z9dmQIxNnD 9XjbKSzYnbM/c/9h4/oRskL+AVZAU3Y= X-MC-Unique: Ot5wjhPmNbaPm-mGJu2axA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 04/20] qapi/parser: preserve indentation in QAPIDoc sections Date: Tue, 14 May 2024 17:57:23 -0400 Message-ID: <20240514215740.940155-5-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724082980100001 Content-Type: text/plain; charset="utf-8" Prior to this patch, a section like this: @name: lorem ipsum dolor sit amet consectetur adipiscing elit would be parsed as: "lorem ipsum\ndolor sit amet\n consectetur adipiscing elit" We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as: "lorem ipsum\n dolor sit amet\n consectetur adipiscing elit" This understandably breaks qapidoc.py; so a new function is added there to re-dedent the text. Once the new generator is merged, this function will not be needed any longer and can be dropped. (I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST.) Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- docs/sphinx/qapidoc.py | 36 +++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 8 ++++++-- tests/qapi-schema/doc-good.out | 32 +++++++++++++++--------------- 3 files changed, 53 insertions(+), 23 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 1655682d4c7..2e3ffcbafb7 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,6 +26,7 @@ =20 import os import re +import textwrap =20 from docutils import nodes from docutils.parsers.rst import Directive, directives @@ -51,6 +52,28 @@ __version__ =3D "1.0" =20 =20 +def dedent(text: str) -> str: + # Temporary: In service of the new QAPI domain, the QAPI doc parser + # now preserves indents in args/members/features text. QAPIDoc does + # not handle this well, so undo that change here. + + # QAPIDoc is being rewritten and will be replaced soon, + # but this function is here in the interim as transition glue. + + lines =3D text.splitlines(True) + if len(lines) > 1: + if re.match(r"\s+", lines[0]): + # First line is indented; description started on + # the line after the name. dedent the whole block. + return textwrap.dedent(text) + else: + # Descr started on same line. Dedent line 2+. + return lines[0] + textwrap.dedent("".join(lines[1:])) + else: + # Descr was a single line; dedent entire line. + return textwrap.dedent(text) + + # fmt: off # Function borrowed from pydash, which is under the MIT license def intersperse(iterable, separator): @@ -169,7 +192,7 @@ def _nodes_for_members(self, doc, what, base=3DNone, br= anches=3DNone): term =3D self._nodes_for_one_member(section.member) # TODO drop fallbacks when undocumented members are outlawed if section.text: - defn =3D section.text + defn =3D dedent(section.text) else: defn =3D [nodes.Text('Not documented')] =20 @@ -207,7 +230,7 @@ def _nodes_for_enum_values(self, doc): termtext.extend(self._nodes_for_ifcond(section.member.ifco= nd)) # TODO drop fallbacks when undocumented members are outlawed if section.text: - defn =3D section.text + defn =3D dedent(section.text) else: defn =3D [nodes.Text('Not documented')] =20 @@ -242,7 +265,7 @@ def _nodes_for_features(self, doc): dlnode =3D nodes.definition_list() for section in doc.features.values(): dlnode +=3D self._make_dlitem( - [nodes.literal('', section.member.name)], section.text) + [nodes.literal('', section.member.name)], dedent(section.t= ext)) seen_item =3D True =20 if not seen_item: @@ -265,9 +288,12 @@ def _nodes_for_sections(self, doc): continue snode =3D self._make_section(section.tag) if section.tag and section.tag.startswith('Example'): - snode +=3D self._nodes_for_example(section.text) + snode +=3D self._nodes_for_example(dedent(section.text)) else: - self._parse_text_into_node(section.text, snode) + self._parse_text_into_node( + dedent(section.text) if section.tag else section.text, + snode, + ) nodelist.append(snode) return nodelist =20 diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 7b13a583ac1..8cdd5334ec6 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -448,7 +448,10 @@ def get_doc_indented(self, doc: 'QAPIDoc') -> Optional= [str]: indent =3D must_match(r'\s*', line).end() if not indent: return line - doc.append_line(line[indent:]) + + # Preserve the indent, it's needed for rST formatting. + doc.append_line(line) + prev_line_blank =3D False while True: self.accept(False) @@ -465,7 +468,8 @@ def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[= str]: self, "unexpected de-indent (expected at least %d spaces)" % indent) - doc.append_line(line[indent:]) + # Again, preserve the indent for ReST. + doc.append_line(line) prev_line_blank =3D True =20 def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 716a9a41026..435f6e6d768 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -117,8 +117,8 @@ doc symbol=3DBase body=3D =20 arg=3Dbase1 -description starts on a new line, -minimally indented + description starts on a new line, + minimally indented doc symbol=3DVariant1 body=3D A paragraph @@ -145,8 +145,8 @@ doc symbol=3DAlternate =20 arg=3Di description starts on the same line -remainder indented the same -@b is undocumented + remainder indented the same + @b is undocumented arg=3Db =20 feature=3Dalt-feat @@ -158,11 +158,11 @@ doc symbol=3Dcmd body=3D =20 arg=3Darg1 -description starts on a new line, -indented + description starts on a new line, + indented arg=3Darg2 description starts on the same line -remainder indented differently + remainder indented differently arg=3Darg3 =20 feature=3Dcmd-feat1 @@ -178,16 +178,16 @@ some section=3DTODO frobnicate section=3DNotes -- Lorem ipsum dolor sit amet -- Ut enim ad minim veniam + - Lorem ipsum dolor sit amet + - Ut enim ad minim veniam =20 -Duis aute irure dolor + Duis aute irure dolor section=3DExample --> in -<- out + -> in + <- out section=3DExamples -- *verbatim* -- {braces} + - *verbatim* + - {braces} section=3DSince 2.10 doc symbol=3Dcmd-boxed @@ -198,9 +198,9 @@ a feature feature=3Dcmd-feat2 another feature section=3DExample --> in + -> in =20 -<- out + <- out doc symbol=3DEVT_BOXED body=3D =20 --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724190; cv=none; d=zohomail.com; s=zohoarc; b=F5FrKu4gegXMdiHPU4MzwXzAzqSIPlFy5rAGBYfrpEs0zEp4ai2eGXNfpJuRCzx0pG+438QacdS+4djv7qiF5wbHafa9rUF1Sc5fX5L5LPvDIHNO/nd7hg7BIH8aoa8u0+hb7Sheu5i7l1f8YB5PLU+BzQ4/5Tnq0d3gX8cMPPg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724190; 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=fqqJCuCczPlWUnIN+2JOb1JkSlAyCnyJxKrh393CyRg=; b=jJuwydC2lNW+9TKadF8bgGxRY4kSR4hDfxxwS4J5aPpYoo+laWFQwER2E28AomWPkawC3TvNBLTdggum+iWX7w57X+Ay9gglIFVQIgt+Vkilf4qNmtl3fY1WzKFQA3UDqzee7YyM2uPhrB83zB5TN2B/33nbfkeQohs3hIH96CE= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724190093942.809674388517; Tue, 14 May 2024 15:03:10 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AM-0005gx-8o; Tue, 14 May 2024 17:58:34 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AK-0005fZ-OD for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:32 -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 1s70AA-0008Ui-It for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:32 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-81-Fj867c8AOvmf5zLIzvXzEA-1; Tue, 14 May 2024 17:58:17 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 725673801EDA; Tue, 14 May 2024 21:58:00 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9FE646BC5; Tue, 14 May 2024 21:57:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723901; 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=fqqJCuCczPlWUnIN+2JOb1JkSlAyCnyJxKrh393CyRg=; b=fGu3kY/akOmlajrsYVFeA+hk/+YhiPa1tbaJbLRNgzu3/e8vsz6mGpT1Dwrb3ECo18Lcv/ TPZqA1Sa7UOqiPi/Sx2sKmLGLHOE3jFzdF9mKgNEEMlqxEqH3vyrlb417tfAjtW5bybX4X dOsgN/EYWQf9SHuZ0h4bzAasfPXTSBs= X-MC-Unique: Fj867c8AOvmf5zLIzvXzEA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 05/20] qapi/parser: adjust info location for doc body section Date: Tue, 14 May 2024 17:57:24 -0400 Message-ID: <20240514215740.940155-6-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724191438100001 Content-Type: text/plain; charset="utf-8" Instead of using the info object for the doc block as a whole, update the info pointer for each call to ensure_untagged_section when the existing section is otherwise empty. This way, Sphinx error information will match precisely to where the text actually starts. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/parser.py | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 8cdd5334ec6..41b9319e5cb 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -662,8 +662,13 @@ def end(self) -> None: =20 def ensure_untagged_section(self, info: QAPISourceInfo) -> None: if self.all_sections and not self.all_sections[-1].tag: - # extend current section - self.all_sections[-1].text +=3D '\n' + section =3D self.all_sections[-1] + # Section is empty so far; update info to start *here*. + if not section.text: + section.info =3D info + else: + # extend current section + self.all_sections[-1].text +=3D '\n' return # start new section section =3D self.Section(info) --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715723935; cv=none; d=zohomail.com; s=zohoarc; b=AvpxcbC5b8/TlI6mFOp8u1dpkuFbO1hyUdQcTpVaTVFctbmpKlV6Vxe7moyRi/Tepop8ihygbSbVoNxEHLoChaZvedy1RmzzfOA/PgaF/kLy8OIZl7yZrPGHBNN5QSIOI4paNX8uyu4A0yBRd6+W1bxDvdce9dAOroNlWqI2iPQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715723935; 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=b8cKk5TmDigdj9d0ZGZVfT5/UEjzyh8U+fRNegmN/Eg=; b=nznqC/oxC4xt40L4NL2sPqh3FuvBtQqpywLUFHm1C9x/7JDrUIIGJTzBD/V8o1NSroH0pijw9fz49ooiJUsdSQYOaYfsNSxhi62RNEhNlmHJfgx86jQepqH77eMAPraKzZ/9Mc1tNJMh/5PjnX4WoGgAwWd6HfEtdxZymjEdduM= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715723935224523.5620410322279; Tue, 14 May 2024 14:58:55 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70A0-0005Zr-HA; Tue, 14 May 2024 17:58:13 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s709x-0005YG-JI for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:10 -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 1s709w-0008RT-0l for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:09 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-556-Ebkdp4JsP2etXOEaDqCVEA-1; Tue, 14 May 2024 17:58:04 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 705A43C00084; Tue, 14 May 2024 21:58:03 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 817006BC6; Tue, 14 May 2024 21:58:00 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723887; 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=b8cKk5TmDigdj9d0ZGZVfT5/UEjzyh8U+fRNegmN/Eg=; b=bG1fcVf81C7kqjaVcR4QRa8zR2KYNm+POLyXkacQReBKyJ1KbzoiDmt7hkp7V3OrrVH6WS ZcbAr4CDXbvPsDmAyzs3Eoj3jHWdvDvb8hjmc9HrWo327w2kEyDuPxPLTXxFn+tJzKJGEl J/I6bjCto75hylG3ubm+xYKLNHyGWFk= X-MC-Unique: Ebkdp4JsP2etXOEaDqCVEA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 06/20] qapi/parser: fix comment parsing immediately following a doc block Date: Tue, 14 May 2024 17:57:25 -0400 Message-ID: <20240514215740.940155-7-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715723936252100009 Content-Type: text/plain; charset="utf-8" If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- 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 41b9319e5cb..161768b8b96 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -587,7 +587,7 @@ def get_doc(self) -> 'QAPIDoc': line =3D self.get_doc_line() first =3D False =20 - self.accept(False) + self.accept() doc.end() return doc =20 --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715723997; cv=none; d=zohomail.com; s=zohoarc; b=PkuD+OD5kmL2H6mTExxNrBnjlbE3LmfzToBtY9BxOHTCrKj8xW+OBnLrSGZy0TUnp+VudDWTUd3gSckg+OIEAv8CIW+2azJoHXrlpSDMzYVE4zeEZg1QCgsAfUKJLXzaV1joUYd3VBN2i0Nm26KynpjCOkSWnrC3wXXwXmVZyW0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715723997; 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=k9rsNEg/0fHHhNyBB2vUXiONXKYYjwjhf809QplAhvk=; b=GDT1ZKNKqEvGzMDvgxSKpZPLe0RxgMg1Z6odgHE067JHBpWIWulXlhEZjTxiqYaxWE+kvipKDy/UtjvGrCfiHECwIMVqVVbKPzT5lLGMC5QxpRUIyZXqx1m5MSgatxjbZ0wRGan7dX+fNGdwYTNk3OFcgRPgKqbInS7Tx/iCjCc= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 171572399766129.57560311156385; Tue, 14 May 2024 14:59:57 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AP-0005ji-B1; Tue, 14 May 2024 17:58:37 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AN-0005iG-RC for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -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 1s70AI-0008Vl-PV for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-339-IiRXHntDOWWzkw1Q8xLwAg-1; Tue, 14 May 2024 17:58:08 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id A03D1801211; Tue, 14 May 2024 21:58:07 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 80F316BC5; Tue, 14 May 2024 21:58:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723906; 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=k9rsNEg/0fHHhNyBB2vUXiONXKYYjwjhf809QplAhvk=; b=GpvjXvIck7rF3nYA9ymGae3dfiJlz5D/X/ps82s9I/OCD+5JFX2rlE/Lw3KQjEsNYLX6/R 8zsrIOLib9SrWgqbmpqKGXYEqqSu60fugTzmhN7cQc+bDrtSLG8k/AFxiBMJlBXG3c51Vd xL2BIEFdBZgYXzki+3St68MT18g8zv0= X-MC-Unique: IiRXHntDOWWzkw1Q8xLwAg-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 07/20] qapi/parser: add semantic 'kind' parameter to QAPIDoc.Section Date: Tue, 14 May 2024 17:57:26 -0400 Message-ID: <20240514215740.940155-8-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715723998467100001 Content-Type: text/plain; charset="utf-8" When iterating all_sections, this is helpful to be able to distinguish "members" from "features"; the only other way to do so is to cross-reference these sections against QAPIDoc.args or QAPIDoc.features, but if the desired end goal for QAPIDoc is to remove everything except all_sections, we need *something* accessible to distinguish them. To keep types simple, add this semantic parameter to the base Section and not just ArgSection; we can use this to filter out paragraphs and tagged sections, too. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/parser.py | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 161768b8b96..cf4cbca1c1f 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -613,21 +613,27 @@ class QAPIDoc: =20 class Section: # pylint: disable=3Dtoo-few-public-methods - def __init__(self, info: QAPISourceInfo, - tag: Optional[str] =3D None): + def __init__( + self, + info: QAPISourceInfo, + tag: Optional[str] =3D None, + kind: str =3D 'paragraph', + ): # section source info, i.e. where it begins self.info =3D info # section tag, if any ('Returns', '@name', ...) self.tag =3D tag # section text without tag self.text =3D '' + # section type - {paragraph, feature, member, tagged} + self.kind =3D kind =20 def append_line(self, line: str) -> None: self.text +=3D line + '\n' =20 class ArgSection(Section): - def __init__(self, info: QAPISourceInfo, tag: str): - super().__init__(info, tag) + def __init__(self, info: QAPISourceInfo, tag: str, kind: str): + super().__init__(info, tag, kind) self.member: Optional['QAPISchemaMember'] =3D None =20 def connect(self, member: 'QAPISchemaMember') -> None: @@ -676,7 +682,7 @@ def ensure_untagged_section(self, info: QAPISourceInfo)= -> None: self.all_sections.append(section) =20 def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: - section =3D self.Section(info, tag) + section =3D self.Section(info, tag, "tagged") if tag =3D=3D 'Returns': if self.returns: raise QAPISemError( @@ -696,20 +702,21 @@ def new_tagged_section(self, info: QAPISourceInfo, ta= g: str) -> None: self.all_sections.append(section) =20 def _new_description(self, info: QAPISourceInfo, name: str, + kind: str, desc: Dict[str, ArgSection]) -> None: if not name: raise QAPISemError(info, "invalid parameter name") if name in desc: raise QAPISemError(info, "'%s' parameter name duplicated" % na= me) - section =3D self.ArgSection(info, '@' + name) + section =3D self.ArgSection(info, '@' + name, kind) self.all_sections.append(section) desc[name] =3D section =20 def new_argument(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, self.args) + self._new_description(info, name, 'member', self.args) =20 def new_feature(self, info: QAPISourceInfo, name: str) -> None: - self._new_description(info, name, self.features) + self._new_description(info, name, 'feature', self.features) =20 def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) @@ -722,7 +729,7 @@ def connect_member(self, member: 'QAPISchemaMember') ->= None: "%s '%s' lacks documentation" % (member.role, member.name)) self.args[member.name] =3D QAPIDoc.ArgSection( - self.info, '@' + member.name) + self.info, '@' + member.name, 'member') self.args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724211; cv=none; d=zohomail.com; s=zohoarc; b=PLd/Re9jrY6+X+Qs9whquSdCeVlvtur2msPEPE0IS09VAnpW/YWyE4O5Q1bPBJgHnB47mmxDUQbsIyu02HiaAHEKtwJ+CJMEXaEwOOC6nP4z2SX+CUNOpil1hH17tGIFLOcLwvIXpXsMStA74PWLvgrV4tZZX3WYgksDTdHhfwk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724211; 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=UmRJ2o/Nw5EvJ/nYmvUPiVWV0dgik2S+bAY6mCQZBXo=; b=aIaXT4rkxbXOEn0wZG5I/nI+IP80fDith/vGuBadKbwBiZ55ux801hoKqjnV3tjd35tqsngCLd3WjOIa/TE370z36/aOE9zLjqFxNBtDzjT0LXQJmBrBsDYJhBuX5IvGGoRlKo9lx602q7jLuj08Zbkv+/Gklq4hu1vPIOuPnrQ= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17157242115481022.6447042314126; Tue, 14 May 2024 15:03:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AN-0005hr-3B; Tue, 14 May 2024 17:58:35 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AL-0005fi-1X for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:33 -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 1s70AE-0008VM-1E for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:32 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-646-Lea9fgNkMj-PXTy1IGsaog-1; Tue, 14 May 2024 17:58:12 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 893371C031AC; Tue, 14 May 2024 21:58:11 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id C5E523C27; Tue, 14 May 2024 21:58:07 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723905; 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=UmRJ2o/Nw5EvJ/nYmvUPiVWV0dgik2S+bAY6mCQZBXo=; b=YqlEQIbQ2vTU7NaIjdiuOQ8HCSkXCk1Ia8MGpP4CUOYsMbYDvzwMX7Zal4YeG0npECfBCl QQH6YMI3hJSF2gcpY97lf+wi1ok5ol59SIBk6AMfmGJpd11aeD/K+T53AJHAL+KlppW2e4 d6N2IkVgZfXeX3qudmIeDhchAzrOYeE= X-MC-Unique: Lea9fgNkMj-PXTy1IGsaog-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 08/20] qapi/parser: differentiate intro and outro paragraphs Date: Tue, 14 May 2024 17:57:27 -0400 Message-ID: <20240514215740.940155-9-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724213452100005 Content-Type: text/plain; charset="utf-8" Add a semantic tag to paragraphs that appear *before* tagged sections/members/features and those that appear after. This will control how they are inlined when doc sections are merged and flattened. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/parser.py | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index cf4cbca1c1f..b1794f71e12 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -503,6 +503,10 @@ def get_doc(self) -> 'QAPIDoc': self.accept(False) line =3D self.get_doc_line() no_more_args =3D False + # Paragraphs before members/features/tagged are "intro" paragr= aphs. + # Any appearing subsequently are "outro" paragraphs. + # This is only semantic metadata for the doc generator. + intro =3D True =20 while line is not None: # Blank lines @@ -532,6 +536,7 @@ def get_doc(self) -> 'QAPIDoc': raise QAPIParseError( self, 'feature descriptions expected') no_more_args =3D True + intro =3D False elif match :=3D self._match_at_name_colon(line): # description if no_more_args: @@ -547,6 +552,7 @@ def get_doc(self) -> 'QAPIDoc': doc.append_line(text) line =3D self.get_doc_indented(doc) no_more_args =3D True + intro =3D False elif match :=3D re.match( r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): @@ -557,13 +563,14 @@ def get_doc(self) -> 'QAPIDoc': doc.append_line(text) line =3D self.get_doc_indented(doc) no_more_args =3D True + intro =3D False elif line.startswith('=3D'): raise QAPIParseError( self, "unexpected '=3D' markup in definition documentati= on") else: # tag-less paragraph - doc.ensure_untagged_section(self.info) + doc.ensure_untagged_section(self.info, intro) doc.append_line(line) line =3D self.get_doc_paragraph(doc) else: @@ -617,7 +624,7 @@ def __init__( self, info: QAPISourceInfo, tag: Optional[str] =3D None, - kind: str =3D 'paragraph', + kind: str =3D 'intro-paragraph', ): # section source info, i.e. where it begins self.info =3D info @@ -625,7 +632,7 @@ def __init__( self.tag =3D tag # section text without tag self.text =3D '' - # section type - {paragraph, feature, member, tagged} + # section type - {-paragraph, feature, member, ta= gged} self.kind =3D kind =20 def append_line(self, line: str) -> None: @@ -666,7 +673,11 @@ def end(self) -> None: raise QAPISemError( section.info, "text required after '%s:'" % section.ta= g) =20 - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: + def ensure_untagged_section( + self, + info: QAPISourceInfo, + intro: bool =3D True, + ) -> None: if self.all_sections and not self.all_sections[-1].tag: section =3D self.all_sections[-1] # Section is empty so far; update info to start *here*. @@ -677,7 +688,8 @@ def ensure_untagged_section(self, info: QAPISourceInfo)= -> None: self.all_sections[-1].text +=3D '\n' return # start new section - section =3D self.Section(info) + kind =3D ("intro" if intro else "outro") + "-paragraph" + section =3D self.Section(info, kind=3Dkind) self.sections.append(section) self.all_sections.append(section) =20 --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724211; cv=none; d=zohomail.com; s=zohoarc; b=nDC/TiS8toQbseQDftFOWlQ9b3GE5R+pn4xL4fvWxLYqgcnhzPzYymVN6YqW913/TbBJB1TXz4Rt/ksu5IzYpbuz5JcqhvsDuemiPdgDv9OQP9B/t7ig1RbSEhJzFUZ5dQT4H1LQVw4bq75XLYRdGFQTvROrQpU3WWlZC3sg3UU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724211; 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=zo3bl/3sPZgA6Nn41k9BPOTu427zWo+0blqcW842RSY=; b=gPDYC6i6WKX5QZEfNz+anmx/vpeh7ay7zEsdYLW+VF/8EAMM405cRcgrRtrIvV/PU4TDZaDyzOeW8ZikS/Y1tiwufnrNpwQMP9TVjjTweqpFsHR9qKAWs4AZBBT+83lkhj41pnv0esyu+gajOAk2TYltjHVoqMbQL1IfBsVsUss= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 171572421177477.8256875380248; Tue, 14 May 2024 15:03:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AL-0005ft-AU; Tue, 14 May 2024 17:58:33 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AJ-0005fM-Cr for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:31 -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 1s70A6-0008To-TR for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:31 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-86-jR8QVqfROzq4I32kuse7Ng-1; Tue, 14 May 2024 17:58:15 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 69E50101A52C; Tue, 14 May 2024 21:58:14 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 9A4286BC0; Tue, 14 May 2024 21:58:11 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723898; 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=zo3bl/3sPZgA6Nn41k9BPOTu427zWo+0blqcW842RSY=; b=DLD+ovgkXHQGd2lC1sg4pmTN6hyYesitAetTRXHttuC0Xy/9RR5Fqd25+7R+aEL3Ar6kBy O1tfdqR1RUfGHJg4WmQ6sVGrgLhed4MhcUOmeY9E64+Ol77IOriBwF6BhVZ4VEkn18V0+X uegbB6TtbipFTmbxnXQkuAgUdeTYzW4= X-MC-Unique: jR8QVqfROzq4I32kuse7Ng-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 09/20] qapi/parser: add undocumented stub members to all_sections Date: Tue, 14 May 2024 17:57:28 -0400 Message-ID: <20240514215740.940155-10-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, SPF_HELO_NONE=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: 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: 1715724213439100003 Content-Type: text/plain; charset="utf-8" This helps simplify the doc generator if it doesn't have to check for undocumented members. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/parser.py | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index b1794f71e12..3cd8e7ee295 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -740,8 +740,24 @@ def connect_member(self, member: 'QAPISchemaMember') -= > None: raise QAPISemError(member.info, "%s '%s' lacks documentation" % (member.role, member.name)) - self.args[member.name] =3D QAPIDoc.ArgSection( - self.info, '@' + member.name, 'member') + + # Insert stub documentation section for missing member docs. + section =3D QAPIDoc.ArgSection( + self.info, f"@{member.name}", "member") + self.args[member.name] =3D section + + # Determine where to insert stub doc. + index =3D 0 + for i, sect in enumerate(self.all_sections): + # insert after these: + if sect.kind in ('intro-paragraph', 'member'): + index =3D i + 1 + # but before these: + elif sect.kind in ('tagged', 'feature', 'outro-paragraph'): + index =3D i + break + self.all_sections.insert(index, section) + self.args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724143; cv=none; d=zohomail.com; s=zohoarc; b=JUCRBwtW14CYbvMH92oE8VzQiRJJb5atUwG4qH47XtDqN1N7BbxAT3DKfRqOikoeUmGoZxVkTAy/Edr+/UX+Un4S8sd+DPPEGBtd+hYa6NsT/jehuznZrPjd/gisJc/LOfxFrUm54G9OV8qoHZcQcPpmihw0e/rhfy4JWUkBi+w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724143; 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=85xPUu21J+/zIGIfScITkU4eoTp7XYVLJD5aCsrUPbs=; b=JpeeubPqlkVc6UE1gemxvdTt6EvMpk+Xy4756O7ODXvwdrYRhO6/9mmyzLn9zYtAEDTKCsAylB/VfEquCnbFEHPUNPVnN0L23p7/1BSAkJZgO0rZ/ZSKR4LKEs8G71t8HeQN6x0SnfEc9Yfs7BVAMApz0pYv/hVF1P6sAHMQgXo= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724143206542.5873658381273; Tue, 14 May 2024 15:02:23 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AT-0005nR-SC; Tue, 14 May 2024 17:58:41 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AO-0005ir-9i for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:36 -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 1s70AK-00006z-0y for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-231-WASL-QZVMXShwt0S-6a1JA-1; Tue, 14 May 2024 17:58:18 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5FA4F3801EC4; Tue, 14 May 2024 21:58:17 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 791863C27; Tue, 14 May 2024 21:58:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723911; 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=85xPUu21J+/zIGIfScITkU4eoTp7XYVLJD5aCsrUPbs=; b=Q946+mf3Un/LZfFhJBpGJvvC8gl6XrROnGpYsk4a7urjKXAKN3EJ/U16hRlmpzWk5YpNE4 Ue6LAbbPX2Cxrt3T3hvJ5Jcarcp/Mq9XIJIFN1PUeVK+AbjhNvoS0UJ/ZYvjhCIQE/dK7f r6Ml2yyBuG2rAI7fZ3aVqSxpMbKJpjY= X-MC-Unique: WASL-QZVMXShwt0S-6a1JA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 10/20] qapi/schema: add __iter__ method to QAPISchemaVariants Date: Tue, 14 May 2024 17:57:29 -0400 Message-ID: <20240514215740.940155-11-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724145214100003 Content-Type: text/plain; charset="utf-8" This just makes it easier to do something like: for var in variants: ... Instead of the more cumbersome and repetitive: for var in variants.variants: ... Especially in conjunction with entities that aren't guaranteed to have variants. Compare: for var in variants.variants if variants else []: ... against: for var in variants or []: ... Update callsites to reflect the new usage pattern. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- docs/sphinx/qapidoc.py | 2 +- scripts/qapi/introspect.py | 4 ++-- scripts/qapi/schema.py | 8 ++++++-- scripts/qapi/types.py | 4 ++-- scripts/qapi/visit.py | 4 ++-- 5 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 2e3ffcbafb7..34e95bd168d 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -204,7 +204,7 @@ def _nodes_for_members(self, doc, what, base=3DNone, br= anches=3DNone): None) =20 if branches: - for v in branches.variants: + for v in branches: if v.type.name =3D=3D 'q_empty': continue assert not v.type.is_implicit() diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py index ac14b20f308..6ec34e055d3 100644 --- a/scripts/qapi/introspect.py +++ b/scripts/qapi/introspect.py @@ -342,7 +342,7 @@ def visit_object_type_flat(self, name: str, info: Optio= nal[QAPISourceInfo], } if branches: obj['tag'] =3D branches.tag_member.name - obj['variants'] =3D [self._gen_variant(v) for v in branches.va= riants] + obj['variants'] =3D [self._gen_variant(v) for v in branches] self._gen_tree(name, 'object', obj, ifcond, features) =20 def visit_alternate_type(self, name: str, info: Optional[QAPISourceInf= o], @@ -353,7 +353,7 @@ def visit_alternate_type(self, name: str, info: Optiona= l[QAPISourceInfo], name, 'alternate', {'members': [Annotated({'type': self._use_type(m.type)}, m.ifcond) - for m in alternatives.variants]}, + for m in alternatives]}, ifcond, features ) =20 diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index d65c35f6ee6..e15e64ea8cb 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -26,6 +26,7 @@ Any, Callable, Dict, + Iterator, List, Optional, Union, @@ -669,7 +670,7 @@ def check(self, schema: QAPISchema) -> None: # so we have to check for potential name collisions ourselves. seen: Dict[str, QAPISchemaMember] =3D {} types_seen: Dict[str, str] =3D {} - for v in self.alternatives.variants: + for v in self.alternatives: v.check_clash(self.info, seen) qtype =3D v.type.alternate_qtype() if not qtype: @@ -700,7 +701,7 @@ def check(self, schema: QAPISchema) -> None: def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc - for v in self.alternatives.variants: + for v in self.alternatives: v.connect_doc(doc) =20 def c_type(self) -> str: @@ -726,6 +727,9 @@ def __init__( self.tag_member: QAPISchemaObjectTypeMember self.variants =3D variants =20 + def __iter__(self) -> Iterator[QAPISchemaVariant]: + return iter(self.variants) + def set_defined_in(self, name: str) -> None: for v in self.variants: v.set_defined_in(name) diff --git a/scripts/qapi/types.py b/scripts/qapi/types.py index 0dd0b00ada3..ad36b55488f 100644 --- a/scripts/qapi/types.py +++ b/scripts/qapi/types.py @@ -166,7 +166,7 @@ def gen_object(name: str, ifcond: QAPISchemaIfCond, objects_seen.add(name) =20 ret =3D '' - for var in variants.variants if variants else (): + for var in variants or (): obj =3D var.type if not isinstance(obj, QAPISchemaObjectType): continue @@ -234,7 +234,7 @@ def gen_variants(variants: QAPISchemaVariants) -> str: ''', c_name=3Dc_name(variants.tag_member.name)) =20 - for var in variants.variants: + for var in variants: if var.type.name =3D=3D 'q_empty': continue ret +=3D var.ifcond.gen_if() diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py index 12f92e429f6..1eca452378c 100644 --- a/scripts/qapi/visit.py +++ b/scripts/qapi/visit.py @@ -141,7 +141,7 @@ def gen_visit_object_members(name: str, ''', c_name=3Dc_name(tag_member.name)) =20 - for var in branches.variants: + for var in branches: case_str =3D c_enum_const(tag_member.type.name, var.name, tag_member.type.prefix) ret +=3D var.ifcond.gen_if() @@ -246,7 +246,7 @@ def gen_visit_alternate(name: str, ''', c_name=3Dc_name(name)) =20 - for var in alternatives.variants: + for var in alternatives: ret +=3D var.ifcond.gen_if() ret +=3D mcgen(''' case %(case)s: --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724222; cv=none; d=zohomail.com; s=zohoarc; b=R+PDebvfs/2tKMde1LBMgqZfW10ELu6xzfixgL7CsFCfB2x1ggAadrd1pLhkwilKgxcnm014Ak89h/EYCu51Fe+JlPEdKbgFZCa2/03DeqRY73Q8Vu2FyEVBY/u+VcR9OVCr50C1ngRZj4i+QqhyPyjSnhpQErcaqSA8DqT7xC4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724222; 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=jfg570U3FRLJ35JfLCL81gkmcp7TkhTnNgfcr0FLQCE=; b=mGBTLFRwBVekkSlFOpCLm8qgzR6+GfwTk+xtrTxh0KXFyGOCKz0RTRgh5DV19goZvKIIZ+VWxK9F6EUlnqVcemDaGJIwXFxIf3zKZTq5zK1az/3H7PB8j5J2dgXydd8z9EATg+eZi4E68uCo4vv76H24uCKsdclcRQXvMT2ArUc= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724222706882.9059812665272; Tue, 14 May 2024 15:03:42 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AQ-0005kN-8y; Tue, 14 May 2024 17:58:38 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AO-0005iK-0C for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:36 -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 1s70AG-0008W3-1l for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-571-8cdUitqFMY-lQQ2HJ4yOaw-1; Tue, 14 May 2024 17:58:21 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 5AAB01C031AC; Tue, 14 May 2024 21:58:20 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7179C6BC0; Tue, 14 May 2024 21:58:17 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723907; 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=jfg570U3FRLJ35JfLCL81gkmcp7TkhTnNgfcr0FLQCE=; b=Hvei26IP+pVxs6ZPE1LKMSujskT5Ft9ygDcAPMwSkNGIQPwYor/ERUB0N+AgYfCcqe2Xcn yIQHX8qYNm2f6qb/QRMNqYqA7UL9KX3wrIi1SCLsZC0IW+YX1bTVrFO7P8A7f5umpy/0YR vfoUtczpNIa2H8g/hnrSXCoAPk/7nfE= X-MC-Unique: 8cdUitqFMY-lQQ2HJ4yOaw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 11/20] qapi/schema: add doc_visible property to QAPISchemaDefinition Date: Tue, 14 May 2024 17:57:30 -0400 Message-ID: <20240514215740.940155-12-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724223526100003 Content-Type: text/plain; charset="utf-8" The intent here is to mark only certain definitions as visible in the end-user docs. All commands and events are inherently visible. Everything else is visible only if it is a member (or a branch member) of a type that is visible, or if it is named as a return type for a command. Notably, this excludes arg_type for commands and events, and any base_types specified for structures/unions. Those objects may still be marked visible if they are named as members from a visible type. This does not necessarily match the data revealed by introspection: in this case, we want anything that we are cross-referencing in generated documentation to be available to target. Some internal and built-in types may be marked visible with this approach, but if they do not have a documentation block, they'll be skipped by the generator anyway. This includes array types and built-in primitives which do not get their own documentation objects. This information is not yet used by qapidoc, which continues to render documentation exactly as it has. This information will be used by the new qapidoc (the "transmogrifier"), to be introduced later. The new generator verifies that all of the objects that should be rendered *are* by failing if any cross-references are missing, verifying everything is in place. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/schema.py | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py index e15e64ea8cb..6025b4e9354 100644 --- a/scripts/qapi/schema.py +++ b/scripts/qapi/schema.py @@ -131,6 +131,7 @@ def __init__( self.doc =3D doc self._ifcond =3D ifcond or QAPISchemaIfCond() self.features =3D features or [] + self.doc_visible =3D False =20 def __repr__(self) -> str: return "<%s:%s at 0x%x>" % (type(self).__name__, self.name, @@ -146,6 +147,10 @@ def check(self, schema: QAPISchema) -> None: for f in self.features: f.check_clash(self.info, seen) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + if mark_self: + self.doc_visible =3D True + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -483,6 +488,10 @@ def check(self, schema: QAPISchema) -> None: self.info.defn_meta if self.info else None) assert not isinstance(self.element_type, QAPISchemaArrayType) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + self.element_type.mark_visible() + def set_module(self, schema: QAPISchema) -> None: self._set_module(schema, self.element_type.info) =20 @@ -607,6 +616,17 @@ def connect_doc(self, doc: Optional[QAPIDoc] =3D None)= -> None: for m in self.local_members: m.connect_doc(doc) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + # Mark this object and its members as visible in the user-facing d= ocs. + if self.doc_visible: + return + + super().mark_visible(mark_self) + for m in self.members: + m.type.mark_visible() + for var in self.branches or []: + var.type.mark_visible(False) + def is_implicit(self) -> bool: # See QAPISchema._make_implicit_object_type(), as well as # _def_predefineds() @@ -698,6 +718,11 @@ def check(self, schema: QAPISchema) -> None: % (v.describe(self.info), types_seen[qt])) types_seen[qt] =3D v.name =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + for var in self.alternatives: + var.type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1056,6 +1081,13 @@ def check(self, schema: QAPISchema) -> None: "command's 'returns' cannot take %s" % self.ret_type.describe()) =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + if self.ret_type: + self.ret_type.mark_visible() + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1112,6 +1144,11 @@ def check(self, schema: QAPISchema) -> None: self.info, "conditional event arguments require 'boxed': true") =20 + def mark_visible(self, mark_self: bool =3D True) -> None: + super().mark_visible(mark_self) + if self.arg_type: + self.arg_type.mark_visible(False) + def connect_doc(self, doc: Optional[QAPIDoc] =3D None) -> None: super().connect_doc(doc) doc =3D doc or self.doc @@ -1488,6 +1525,9 @@ def check(self) -> None: ent.set_module(self) for doc in self.docs: doc.check() + for ent in self._entity_list: + if isinstance(ent, (QAPISchemaCommand, QAPISchemaEvent)): + ent.mark_visible() =20 def visit(self, visitor: QAPISchemaVisitor) -> None: visitor.visit_begin(self) --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724143; cv=none; d=zohomail.com; s=zohoarc; b=dO5h8bFe0cxPsjI7RmvpaaOFxbxh7JJsPSdP/vtOCFDGVMgpPTXUGCUS0yxkep+aougtYG3NZP8+dGk458YSi58oB0nGUA9WdycB9Sv/eVmcYhsjOB207iJ2LnyZfBzU/0sf+Sz4lBhVAI/gV9LMrONL0WpKImK8cfxXhbmTdIQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724143; 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=ncArWPcCIbytAbF/odN9+d1qLIA0sIT1UcBoo/l5JNg=; b=A/IM0UwEsrBjPx8biMcuudmIV8iSl+AJKX4BxtU3kbREp27Y5IfMNleqlpTaUN99LU6DHlXggzOwVjAJN8nMn6zhHsJ3V94IHAix8bhXn/briQE5jCFZYSkCxhccwSjcAw267boFFggV+jqkDv9uZCGzYB+86be82DJ7eus/8Ro= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724143311677.4004689513743; Tue, 14 May 2024 15:02:23 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AV-0005oA-I3; Tue, 14 May 2024 17:58:43 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AP-0005jj-9q for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:37 -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 1s70AN-00008D-3o for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:37 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-695-0i3DYVDuNmaO7CNRSuwpjg-1; Tue, 14 May 2024 17:58:24 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 6AC5C18188A1; Tue, 14 May 2024 21:58:23 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 708843C27; Tue, 14 May 2024 21:58:20 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723914; 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=ncArWPcCIbytAbF/odN9+d1qLIA0sIT1UcBoo/l5JNg=; b=WKBchEFCJwxd8XclGLEY9KJ+B+Rsd03PzvcLEpuUi8RQwfK1gbfrBMcSGWuGcneR7rsARN CyTrQpDvFfJP4zhCPBLhOD1Dec8AKj4wkI4PfQzQbLxSlLH6TlOPpvUEwTp+uuVXAzcW1V vXoR0yeeYzFI5ALaVL9dGMuA5gi2IrQ= X-MC-Unique: 0i3DYVDuNmaO7CNRSuwpjg-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 12/20] qapi/source: allow multi-line QAPISourceInfo advancing Date: Tue, 14 May 2024 17:57:31 -0400 Message-ID: <20240514215740.940155-13-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724145186100001 Content-Type: text/plain; charset="utf-8" This is for the sake of the new rST generator (the "transmogrifier") so we can advance multiple lines on occasion while keeping the generated<-->source mappings accurate. next_line now simply takes an optional n parameter which chooses the number of lines to advance. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- scripts/qapi/source.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/qapi/source.py b/scripts/qapi/source.py index 7b379fdc925..ffdc3f482ac 100644 --- a/scripts/qapi/source.py +++ b/scripts/qapi/source.py @@ -47,9 +47,9 @@ def set_defn(self, meta: str, name: str) -> None: self.defn_meta =3D meta self.defn_name =3D name =20 - def next_line(self: T) -> T: + def next_line(self: T, n: int =3D 1) -> T: info =3D copy.copy(self) - info.line +=3D 1 + info.line +=3D n return info =20 def loc(self) -> str: --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724223; cv=none; d=zohomail.com; s=zohoarc; b=Oa3f6krARetyEqKlHLr2mCJntQiBt7QAjEyPd6LsWO0v/F8MH/S35ByU/i4/LSTS0QkF4HEVlX9tDOVEZkbTTVGO+22lid3oRXkA/iP1pwoapW4AXnw9HfjAPzUMirVTpGXxmqxghA9woHjvWFwLbXtCNEO3OEkrbSWAvY6iI/M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724223; 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=+2kDCXDoldCk9Iu0s+DkhAlixvACFVCHN/kg8zLipPY=; b=oIP34RZm7lnQNUO3AuwhXm/Gurw93kReaXB1749PG1yGT46EbgdFsYE4Hxx96cEXI6MVNr6461RRKw0iAzg9D9jyGkV/O4bsqG/DgLLDHOq8MSknYXev6/uatIHTNLpcg4P0SBpRprqiKUop1UNP9iyJXxH6+cRqAWzpSnZJeEM= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 17157242230058.737465307798743; Tue, 14 May 2024 15:03:43 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AR-0005lP-El; Tue, 14 May 2024 17:58:39 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AN-0005iH-UP for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -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 1s70AJ-00006l-Co for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:35 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-591-OyDoAmiNP52l-g4uPCLcbQ-1; Tue, 14 May 2024 17:58:27 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B24703806704; Tue, 14 May 2024 21:58:26 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 7AC176BC5; Tue, 14 May 2024 21:58:23 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723910; 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=+2kDCXDoldCk9Iu0s+DkhAlixvACFVCHN/kg8zLipPY=; b=MjNTGumbjZbQ6mj3x0xq/IaWLx1uR6Rz+GNid8Gw5jPsRFk7vmM/h4uvfF0gKYyvGeGsNu psRB7tOg3/PbL/WvwNtVPDU6gT8fFPTodDaTR6evSY0JZFask0mXQymjEcSFDPnIfZ8S8U r7shnsXw4oeIYOHr5df7E71+N4gu3tI= X-MC-Unique: OyDoAmiNP52l-g4uPCLcbQ-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 13/20] docs/qapidoc: fix nested parsing under untagged sections Date: Tue, 14 May 2024 17:57:32 -0400 Message-ID: <20240514215740.940155-14-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724223492100001 Content-Type: text/plain; charset="utf-8" Sphinx does not like sections without titles, because it wants to convert every section into a reference. When there is no title, it struggles to do this and transforms the tree inproperly. Depending on the rST used, this may result in an assertion error deep in the docutils HTMLWriter. When parsing an untagged section (free paragraphs), skip making a hollow section and instead append the parse results to the prior section. Many Bothans died to bring us this information. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- docs/sphinx/qapidoc.py | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 34e95bd168d..cfc0cf169ef 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -286,14 +286,20 @@ def _nodes_for_sections(self, doc): if section.tag and section.tag =3D=3D 'TODO': # Hide TODO: sections continue + + if not section.tag: + # Sphinx cannot handle sectionless titles; + # Instead, just append the results to the prior section. + container =3D nodes.container() + self._parse_text_into_node(section.text, container) + nodelist +=3D container.children + continue + snode =3D self._make_section(section.tag) - if section.tag and section.tag.startswith('Example'): + if section.tag.startswith('Example'): snode +=3D self._nodes_for_example(dedent(section.text)) else: - self._parse_text_into_node( - dedent(section.text) if section.tag else section.text, - snode, - ) + self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist =20 --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715723990; cv=none; d=zohomail.com; s=zohoarc; b=KMJUzsWkmq56a7f3EX0efEfGOsXeE1KlohnfTXNNZrMBKjdePqNJhE+jcWCLS5uLSgZTsvA+6i4FNhl0+g8/wXpwsNSbM09hr71+6bfA1xIf8D/U/6xcnkhkwMxGjrHPfEMIVJkP64vHR1AfHQIh+qmxz5XjwPZh8Q5FVg4Z21M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715723990; 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=mwjHYLm6iycQ6pC7rtrFtY9E94ZsxNimekXIcigYkpk=; b=CLLr0JJ3f7S+O5Tuvycv95A1J/3H/c0WR3wdBR96lzzcB2OAioxvw9gnHq4TEhsOxoLKTaFpKgRxgJmBfuCt7qNxDG2ukWMQs+hOe5ViYq+piMEfBsQ1kj4Bw4/WwkP4QBCu57keIHVbmWB0bpYt59PMZTSepk0SB3qorvE88go= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715723990466570.2168021993688; Tue, 14 May 2024 14:59:50 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70Ab-0005vK-Fu; Tue, 14 May 2024 17:58:49 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AY-0005rB-VO for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:47 -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 1s70AX-0000Bw-8h for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:46 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-68-Cmwpts9QM_ONh6gnzl4Y3A-1; Tue, 14 May 2024 17:58:30 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id CAD183801EC4; Tue, 14 May 2024 21:58:29 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id C51723C27; Tue, 14 May 2024 21:58:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723924; 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=mwjHYLm6iycQ6pC7rtrFtY9E94ZsxNimekXIcigYkpk=; b=fijN9WQJ/m6+6O2IRZwLQmY+HZ30O3gqf2nki8ILcpHyIH0ffm7eFIfxZst7IXIKCV+Ztv uBWgTwzUfEY3G5kPPiiGkY3V5uVr53YwSVUNS4EwcLnNT6HJNmf9SNgPd459abSsBfNjk1 34GfX4qaWI9il7OARGyPlL6/is++FkA= X-MC-Unique: Cmwpts9QM_ONh6gnzl4Y3A-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 14/20] qapi: fix non-compliant JSON examples Date: Tue, 14 May 2024 17:57:33 -0400 Message-ID: <20240514215740.940155-15-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715723992402100003 Content-Type: text/plain; charset="utf-8" If we parse all examples as QMP, we need them to conform to a standard so that they render correctly. Once the QMP lexer is active for examples, these will produce warning messages and fail the build. The QMP lexer still supports elisions, but they must be represented as the value "...", so two examples have been adjusted to support that format here. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/control.json | 3 ++- qapi/machine.json | 2 +- qapi/migration.json | 2 +- qapi/misc.json | 3 ++- qapi/net.json | 6 +++--- qapi/rocker.json | 2 +- qapi/ui.json | 2 +- 7 files changed, 11 insertions(+), 9 deletions(-) diff --git a/qapi/control.json b/qapi/control.json index 6bdbf077c2e..10c906fa0e7 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -145,7 +145,8 @@ # }, # { # "name":"system_powerdown" -# } +# }, +# ... # ] # } # diff --git a/qapi/machine.json b/qapi/machine.json index bce6e1bbc41..64a77557571 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1057,7 +1057,7 @@ # "vcpus-count": 1 }, # { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core", # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} -# ]}' +# ]} # # For pc machine type started with -smp 1,maxcpus=3D2: # diff --git a/qapi/migration.json b/qapi/migration.json index a351fd37143..89047d46c7c 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -2078,7 +2078,7 @@ # Example: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, -# 'sample-pages': 512}= } +# "sample-pages": 512}= } # <- { "return": {} } # # Measure dirty rate using dirty bitmap for 500 milliseconds: diff --git a/qapi/misc.json b/qapi/misc.json index ec30e5c570a..4b41e15dcd4 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -287,7 +287,8 @@ # # Example: # -# -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123.= .", fdname": "skclient" } } +# -> { "execute": "get-win32-socket", +# "arguments": { "info": "abcd123..", "fdname": "skclient" } } # <- { "return": {} } ## { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'},= 'if': 'CONFIG_WIN32' } diff --git a/qapi/net.json b/qapi/net.json index 0f5a259475e..c19df435a53 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -1003,9 +1003,9 @@ # # Example: # -# <- { 'event': 'NETDEV_STREAM_DISCONNECTED', -# 'data': {'netdev-id': 'netdev0'}, -# 'timestamp': {'seconds': 1663330937, 'microseconds': 526695} } +# <- { "event": "NETDEV_STREAM_DISCONNECTED", +# "data": {"netdev-id": "netdev0"}, +# "timestamp": {"seconds": 1663330937, "microseconds": 526695} } ## { 'event': 'NETDEV_STREAM_DISCONNECTED', 'data': { 'netdev-id': 'str' } } diff --git a/qapi/rocker.json b/qapi/rocker.json index 5635cf174fd..f5225eb62cc 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -250,7 +250,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...more...}, +# {...}, # ]} ## { 'command': 'query-rocker-of-dpa-flows', diff --git a/qapi/ui.json b/qapi/ui.json index f610bce118a..c12f5292571 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -361,7 +361,7 @@ # "channel-id": 0, # "tls": false # }, -# [ ... more channels follow ... ] +# ... # ] # } # } --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724183; cv=none; d=zohomail.com; s=zohoarc; b=RQxLKjnEtA4t5PaPBD68TZbZ3/NKHFQWruHvh+u64lI9JsTrsW9EOvCV5EgLO0Y0VJAz8D65xJLwiDgbUPT4/SDSNGaQA5eK+ghiPP+VHYQFVdBpR2MhVhQW2e5uPjmeXVyCVa25x2VnOoReyaIzWLmb+WJw5YnGrkszv2mhz7k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724183; 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=Sr9surEDs9NJNE7QhRLrNBImeHlnfOAEwLxKeLnQ19I=; b=bO/9N/4icp3VueT0SzaSlenRoEuRiMPD1nRnpKpd9rK+4yZP40N+DT2UBesL62rtN9ElgeSstp1om7TM2VtukH6RsUvFwYBRLs1N/8c0pXKsOGFoc9E3saIJxlF81SWUckSp84GuaFcF29LjonbENMBY09ULurGqeMKQZrAqTpM= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724183448786.810323024265; Tue, 14 May 2024 15:03:03 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AW-0005q2-6Q; Tue, 14 May 2024 17:58:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AR-0005lU-Oo for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:39 -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 1s70AP-00009P-CC for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:39 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-253-nN_yexIePkaGz3WTI0BTLw-1; Tue, 14 May 2024 17:58:33 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id C312E101A55E; Tue, 14 May 2024 21:58:32 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id DF8E06BC0; Tue, 14 May 2024 21:58:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723916; 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=Sr9surEDs9NJNE7QhRLrNBImeHlnfOAEwLxKeLnQ19I=; b=WKWQ4eHMLb16zcQClripPwC34Y5mpiFDrEwmF7aMrcepc99No04xM6UuJCP4vaCrqqBjhy KnACfgAnukI1M/Jw4k050r0Dd7LAejIIx1w5oJ0N+90QmxQ6Oea8022GYwRA+c/2ThZQcM Hu9hVCxwReABhCOHsCkHTC1uBmGgJiM= X-MC-Unique: nN_yexIePkaGz3WTI0BTLw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 15/20] qapi: remove developer factoring comments from QAPI doc blocks Date: Tue, 14 May 2024 17:57:34 -0400 Message-ID: <20240514215740.940155-16-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724185417100001 Content-Type: text/plain; charset="utf-8" This is part of a project to overhaul the QMP reference manual. One goal of this overhaul is to "inline" inherited argument sections into command reference sections. A consequence of this design decision is that inherited doc block sections need to be merged with the inheritor's sections. When documentation is written for types whose primary purpose is to be inherited by other types, we need to know how to merge those paragraphs into the descendent. Much of the time, these paragraphs aren't actually useful to end users. Either remove information that's of little to no use to *either* audience, and convert what's left to garden-variety comments to prevent it from showing up in rendered documentation. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/audio.json | 5 ++--- qapi/block-core.json | 47 ++++++++++++++++++------------------------ qapi/block-export.json | 10 ++++----- qapi/char.json | 5 ++--- qapi/crypto.json | 33 ++++++++++++----------------- qapi/machine.json | 10 ++++----- qapi/net.json | 7 ++----- qapi/qom.json | 30 +++++++++++---------------- qapi/ui.json | 14 ------------- 9 files changed, 59 insertions(+), 102 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 519697c0cd8..ee09cd231b6 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -10,11 +10,10 @@ # =3D Audio ## =20 -## -# @AudiodevPerDirectionOptions: -# # General audio backend options that are used for both playback and # recording. +## +# @AudiodevPerDirectionOptions: # # @mixing-engine: use QEMU's mixing engine to mix all streams inside # QEMU and convert audio formats when not supported by the diff --git a/qapi/block-core.json b/qapi/block-core.json index 746d1694c25..64fe5240cc9 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -267,10 +267,9 @@ 'file': 'ImageInfoSpecificFileWrapper' } } =20 -## -# @BlockNodeInfo: -# # Information about a QEMU image file +## +# @BlockNodeInfo: # # @filename: name of the image file # @@ -1494,8 +1493,6 @@ ## # @BlockdevSnapshotSync: # -# Either @device or @node-name must be set but not both. -# # @device: the name of the device to take a snapshot of. # # @node-name: graph node name to generate the snapshot from (Since @@ -1512,6 +1509,9 @@ # # @mode: whether and how QEMU should create a new image, default is # 'absolute-paths'. +# +# Note: Either @device or @node-name must be set but not both. +# ## { 'struct': 'BlockdevSnapshotSync', 'data': { '*device': 'str', '*node-name': 'str', @@ -2139,10 +2139,9 @@ 'data': 'DriveMirror', 'allow-preconfig': true } =20 -## -# @DriveMirror: -# # A set of parameters describing drive mirror setup. +## +# @DriveMirror: # # @job-id: identifier for the newly-created block job. If omitted, # the device name will be used. (Since 2.7) @@ -2553,10 +2552,9 @@ '*auto-finalize': 'bool', '*auto-dismiss': 'bool' }, 'allow-preconfig': true } =20 -## -# @BlockIOThrottle: -# # A set of parameters describing block throttling. +## +# @BlockIOThrottle: # # @device: Block device name # @@ -3073,10 +3071,9 @@ { 'struct': 'BlockJobChangeOptionsMirror', 'data': { 'copy-mode' : 'MirrorCopyMode' } } =20 -## -# @BlockJobChangeOptions: -# # Block job options that can be changed after job creation. +## +# @BlockJobChangeOptions: # # @id: The job identifier # @@ -3332,11 +3329,10 @@ 'data': { 'dir': 'str', '*fat-type': 'int', '*floppy': 'bool', '*label': 'str', '*rw': 'bool' } } =20 -## -# @BlockdevOptionsGenericFormat: -# # Driver specific block device options for image format that have no # option besides their data source. +## +# @BlockdevOptionsGenericFormat: # # @file: reference to or definition of the data source block device # @@ -3363,11 +3359,10 @@ 'data': { '*key-secret': 'str', '*header': 'BlockdevRef'} } =20 -## -# @BlockdevOptionsGenericCOWFormat: -# # Driver specific block device options for image format that have no # option besides their data source and an optional backing file. +## +# @BlockdevOptionsGenericCOWFormat: # # @backing: reference to or definition of the backing file block # device, null disables the backing file entirely. Defaults to @@ -4385,11 +4380,10 @@ '*page-cache-size': 'int', '*debug': 'int' } } =20 -## -# @BlockdevOptionsCurlBase: -# # Driver specific block device options shared by all protocols # supported by the curl backend. +## +# @BlockdevOptionsCurlBase: # # @url: URL of the image file # @@ -4645,11 +4639,10 @@ 'data': { 'target': 'BlockdevRef', '*bitmap': 'BlockDirtyBitmap', '*on-cbw-error': 'OnCbwError', '*cbw-timeout': 'uint32' } } =20 -## -# @BlockdevOptions: -# # Options for creating a block device. Many options are available for -# all block devices, independent of the block driver: +# all block devices, independent of the block driver. +## +# @BlockdevOptions: # # @driver: block driver name # diff --git a/qapi/block-export.json b/qapi/block-export.json index 3919a2d5b9d..dc328097a94 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -77,11 +77,10 @@ '*max-connections': 'uint32' }, 'allow-preconfig': true } =20 -## -# @BlockExportOptionsNbdBase: -# # An NBD block export (common options shared between nbd-server-add # and the NBD branch of block-export-add). +## +# @BlockExportOptionsNbdBase: # # @name: Export name. If unspecified, the @device parameter is used # as the export name. (Since 2.12) @@ -213,10 +212,9 @@ '*logical-block-size': 'size', '*serial': 'str' } } =20 -## -# @NbdServerAddOptions: -# # An NBD block export, per legacy nbd-server-add command. +## +# @NbdServerAddOptions: # # @device: The device name or node name of the node to be exported # diff --git a/qapi/char.json b/qapi/char.json index 777dde55d97..ab4c23976ed 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -189,10 +189,9 @@ 'data': {'device': 'str', 'size': 'int', '*format': 'DataFormat'}, 'returns': 'str' } =20 -## -# @ChardevCommon: -# # Configuration shared across all chardev backends +## +# @ChardevCommon: # # @logfile: The name of a logfile to save output # diff --git a/qapi/crypto.json b/qapi/crypto.json index e102be337bb..d4ac5f23c8c 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -163,10 +163,9 @@ # 'prefix': 'QCRYPTO_BLOCK_FORMAT', 'data': ['qcow', 'luks']} =20 -## -# @QCryptoBlockOptionsBase: -# # The common options that apply to all full disk encryption formats +## +# @QCryptoBlockOptionsBase: # # @format: the encryption format # @@ -175,10 +174,9 @@ { 'struct': 'QCryptoBlockOptionsBase', 'data': { 'format': 'QCryptoBlockFormat' }} =20 -## -# @QCryptoBlockOptionsQCow: -# # The options that apply to QCow/QCow2 AES-CBC encryption format +## +# @QCryptoBlockOptionsQCow: # # @key-secret: the ID of a QCryptoSecret object providing the # decryption key. Mandatory except when probing image for @@ -189,11 +187,10 @@ { 'struct': 'QCryptoBlockOptionsQCow', 'data': { '*key-secret': 'str' }} =20 +# The options that apply to LUKS encryption format: ## # @QCryptoBlockOptionsLUKS: # -# The options that apply to LUKS encryption format -# # @key-secret: the ID of a QCryptoSecret object providing the # decryption key. Mandatory except when probing image for # metadata only. @@ -203,10 +200,9 @@ { 'struct': 'QCryptoBlockOptionsLUKS', 'data': { '*key-secret': 'str' }} =20 -## -# @QCryptoBlockCreateOptionsLUKS: -# # The options that apply to LUKS encryption format initialization +## +# @QCryptoBlockCreateOptionsLUKS: # # @cipher-alg: the cipher algorithm for data encryption Currently # defaults to 'aes-256'. @@ -268,11 +264,10 @@ 'data': { 'qcow': 'QCryptoBlockOptionsQCow', 'luks': 'QCryptoBlockCreateOptionsLUKS' } } =20 -## -# @QCryptoBlockInfoBase: -# # The common information that applies to all full disk encryption # formats +## +# @QCryptoBlockInfoBase: # # @format: the encryption format # @@ -424,10 +419,9 @@ 'data': { 'luks': 'QCryptoBlockAmendOptionsLUKS' } } =20 -## -# @SecretCommonProperties: -# # Properties for objects of classes derived from secret-common. +## +# @SecretCommonProperties: # # @loaded: if true, the secret is loaded immediately when applying # this option and will probably fail when processing the next @@ -490,10 +484,9 @@ 'base': 'SecretCommonProperties', 'data': { 'serial': 'int32' } } =20 -## -# @TlsCredsProperties: -# # Properties for objects of classes derived from tls-creds. +## +# @TlsCredsProperties: # # @verify-peer: if true the peer credentials will be verified once the # handshake is completed. This is a no-op for anonymous diff --git a/qapi/machine.json b/qapi/machine.json index 64a77557571..35cca12ba41 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -497,10 +497,9 @@ { 'enum': 'NumaOptionsType', 'data': [ 'node', 'dist', 'cpu', 'hmat-lb', 'hmat-cache' ] } =20 -## -# @NumaOptions: -# # A discriminated record of NUMA options. (for OptsVisitor) +## +# @NumaOptions: # # @type: NUMA option type # @@ -1198,10 +1197,9 @@ { 'event': 'BALLOON_CHANGE', 'data': { 'actual': 'int' } } =20 -## -# @HvBalloonInfo: -# # hv-balloon guest-provided memory status information. +## +# @HvBalloonInfo: # # @committed: the amount of memory in use inside the guest plus the # amount of the memory unusable inside the guest (ballooned out, diff --git a/qapi/net.json b/qapi/net.json index c19df435a53..dc616d010f0 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -722,10 +722,9 @@ { 'name': 'vmnet-shared', 'if': 'CONFIG_VMNET' }, { 'name': 'vmnet-bridged', 'if': 'CONFIG_VMNET' }] } =20 -## -# @Netdev: -# # Captures the configuration of a network device. +## +# @Netdev: # # @id: identifier for monitor commands. # @@ -894,8 +893,6 @@ ## # @AnnounceParameters: # -# Parameters for self-announce timers -# # @initial: Initial delay (in ms) before sending the first GARP/RARP # announcement # diff --git a/qapi/qom.json b/qapi/qom.json index 38dde6d785a..8f0601859b1 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -272,11 +272,10 @@ '*max_queue_size': 'uint32', '*vnet_hdr_support': 'bool' } } =20 -## -# @CryptodevBackendProperties: -# # Properties for cryptodev-backend and cryptodev-backend-builtin # objects. +## +# @CryptodevBackendProperties: # # @queues: the number of queues for the cryptodev backend. Ignored # for cryptodev-backend and must be 1 for @@ -338,10 +337,9 @@ { 'enum': 'NetfilterInsert', 'data': [ 'before', 'behind' ] } =20 -## -# @NetfilterProperties: -# # Properties for objects of classes derived from netfilter. +## +# @NetfilterProperties: # # @netdev: id of the network device backend to filter # @@ -516,10 +514,9 @@ '*repeat': 'bool', '*grab-toggle': 'GrabToggleKeys' } } =20 -## -# @EventLoopBaseProperties: -# # Common properties for event loops +## +# @EventLoopBaseProperties: # # @aio-max-batch: maximum number of requests in a batch for the AIO # engine, 0 means that the engine will use its default. @@ -576,10 +573,9 @@ 'base': 'EventLoopBaseProperties', 'data': {} } =20 -## -# @MemoryBackendProperties: -# # Properties for objects of classes derived from memory-backend. +## +# @MemoryBackendProperties: # # @merge: if true, mark the memory as mergeable (default depends on # the machine type) @@ -826,10 +822,9 @@ 'data': { 'pci-dev': 'str', 'node': 'uint32' } } =20 -## -# @RngProperties: -# # Properties for objects of classes derived from rng. +## +# @RngProperties: # # @opened: if true, the device is opened immediately when applying # this option and will probably fail when processing the next @@ -1008,10 +1003,9 @@ { 'name': 'x-vfio-user-server', 'features': [ 'unstable' ] } ] } =20 -## -# @ObjectOptions: -# # Describes the options of a user creatable QOM object. +## +# @ObjectOptions: # # @qom-type: the class name for the object to be created # diff --git a/qapi/ui.json b/qapi/ui.json index c12f5292571..2d0aa407aca 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -39,8 +39,6 @@ ## # @SetPasswordOptions: # -# Options for set_password. -# # @protocol: # - 'vnc' to modify the VNC server password # - 'spice' to modify the Spice server password @@ -94,8 +92,6 @@ ## # @ExpirePasswordOptions: # -# General options for expire_password. -# # @protocol: # - 'vnc' to modify the VNC server expiration # - 'spice' to modify the Spice server expiration @@ -206,8 +202,6 @@ ## # @SpiceBasicInfo: # -# The basic information for SPICE network connection -# # @host: IP address # # @port: port number @@ -469,8 +463,6 @@ ## # @VncBasicInfo: # -# The basic information for vnc network connection -# # @host: IP address # # @service: The service name of the vnc port. This may depend on the @@ -1598,8 +1590,6 @@ ## # @DisplayReloadOptions: # -# Options of the display configuration reload. -# # @type: Specify the display type. # # Since: 6.0 @@ -1641,8 +1631,6 @@ ## # @DisplayUpdateOptionsVNC: # -# Specify the VNC reload options. -# # @addresses: If specified, change set of addresses to listen for # connections. Addresses configured for websockets are not # touched. @@ -1655,8 +1643,6 @@ ## # @DisplayUpdateOptions: # -# Options of the display configuration reload. -# # @type: Specify the display type. # # Since: 7.1 --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724211; cv=none; d=zohomail.com; s=zohoarc; b=mRK5GccrXCABXlBQ2sC3K9vRW3zq8YH7+qAd6cFda94cEfoo+pJLK07Rr9NW7ex00w0T7+BHRNQF8tiaJ9jT1FGPKjEkJ2NasBZ2a8FU8wZYUzQFr2ra7+BudVE9JC86ti+sopD2Q5CAW6zb4Sj3nOAjFJ4sfno6ZY9R+B/mnI4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724211; 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=j3+82aPY5MN5L73YVE9yUVjV8BWu/aOCzfXUbGS1N4o=; b=fmmOmxhwq406Gv3L8IT1JsEJqYDlkcm1qgKptSoHMEBKqNCwU7AxdW8ziyunZEBXgp8w+nrB8Gh3Vv0ek0iH9qrLgGe1Sdn0gNKBcejOSTCQxoX1s3Mr5dZycex/1TfAwQSKSBXrZE2BYwX3QQfqA+v7cKwJY0PfF4PPS+8dVNw= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724211402650.5725866001878; Tue, 14 May 2024 15:03:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70AW-0005qn-TA; Tue, 14 May 2024 17:58:44 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AV-0005nt-00 for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:43 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70AT-0000Aw-JT for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:42 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-350-PaDRCbY_P8qO5yc1RkFzhw-1; Tue, 14 May 2024 17:58:36 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id B5454801211; Tue, 14 May 2024 21:58:35 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id D83DD3C27; Tue, 14 May 2024 21:58:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723921; 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=j3+82aPY5MN5L73YVE9yUVjV8BWu/aOCzfXUbGS1N4o=; b=P9qiNAaPYW5ZyEtuByFUs0ZVcDFlaBBTQaq1hyUC0usUYwQjTyDmYtgA8GuzeUfc5WpX2V g0c7Pm7wDeM+/3BULEjgEDyRqSDA//i0eEUsFuONDaXjF05eZilWhoY1L253R/EnOQp/Ip +GGzyzoigZHOKIXtGJtlGolzW/WA7BE= X-MC-Unique: PaDRCbY_P8qO5yc1RkFzhw-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 16/20] qapi: rewrite StatsFilter comment Date: Tue, 14 May 2024 17:57:35 -0400 Message-ID: <20240514215740.940155-17-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724213440100004 Content-Type: text/plain; charset="utf-8" Rewrite the StatsFilter intro paragraph to be more meaningful to end-users when it is inlined in generated documentation. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/stats.json | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/qapi/stats.json b/qapi/stats.json index 578b52c7ef7..c4a9f3ff70e 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -112,10 +112,6 @@ ## # @StatsFilter: # -# The arguments to the query-stats command; specifies a target for -# which to request statistics and optionally the required subset of -# information for that target. -# # @target: the kind of objects to query. Note that each possible # target may enable additional filtering options # @@ -183,8 +179,8 @@ # Return runtime-collected statistics for objects such as the VM or # its vCPUs. # -# The arguments are a StatsFilter and specify the provider and objects -# to return statistics about. +# The arguments specify a target for which to request statistics and +# optionally the required subset of information for that target. # # Returns: a list of StatsResult, one for each provider and object # (e.g., for each vCPU). --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724098; cv=none; d=zohomail.com; s=zohoarc; b=dFgOaxhWTrT3EqY6pfQPOyFS3D2FbKChly3AFkfS2wFxWcoybIMSS/67qAcs12fcyri92b+NoC7slq/uOUHvipVggH3e5vUG7oEhp/Wv9pYgOGRCgE9TQSwD17hAoK7WbD3jNr/sKxsWT4k5fOscWO5iUzbzzv30g7Wdx0a+Bx8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724098; 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=8REDNf33ucIzZ95MV/W0jx8cBWgx1MGIREXz05bgb1c=; b=PPZ0C4JTTo2WB/n978oX3lbsa+Gg+jMZ+gYQwdjw4+LXsV5PqVfP6zmD34iE1n+JZ2m1KRaBfHbKeOqMVH4ujESP2blPeZdtlsqxdDYkT2F6ELXdm946s3v5dFHcntZh9pC9i58JKjDn9O4x/Ng4O76K3bOWXj/3m/h3xm2CIeo= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724098098907.0084396840009; Tue, 14 May 2024 15:01:38 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70Ad-0005wx-2c; Tue, 14 May 2024 17:58:51 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70Aa-0005sC-Gx for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:48 -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 1s70AY-0000CO-Ty for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:48 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-582-_UIezUIdOXSdS_UKC8ZRRA-1; Tue, 14 May 2024 17:58:42 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id D07FB3801ECE; Tue, 14 May 2024 21:58:38 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id C4B196BC5; Tue, 14 May 2024 21:58:35 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723926; 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=8REDNf33ucIzZ95MV/W0jx8cBWgx1MGIREXz05bgb1c=; b=TDLCWFEVlMZx4MGKswaWdBm2iLmbpEzJCo+wuzRv4IrZqHLpQA4rEjJjcoXKvv4Qghzys6 bqvck6thbmGEtly1KnhWePrvqyugp68UUY+JtCkZFJFrp6UV2Pdet3cyFC83kKVv9lI3SK 0pItudRDfTM9vNSAt3sfNRd9z9fNC8o= X-MC-Unique: _UIezUIdOXSdS_UKC8ZRRA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 17/20] qapi: rewrite BlockExportOptions doc block Date: Tue, 14 May 2024 17:57:36 -0400 Message-ID: <20240514215740.940155-18-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724099006100001 Content-Type: text/plain; charset="utf-8" Rephrase this paragraph so that it can apply to any commands that inherit from this object. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/block-export.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/qapi/block-export.json b/qapi/block-export.json index dc328097a94..550763a9f6a 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -342,9 +342,6 @@ ## # @BlockExportOptions: # -# Describes a block export, i.e. how single node should be exported on -# an external interface. -# # @type: Block export type # # @id: A unique identifier for the block export (across all export @@ -396,6 +393,9 @@ # # Creates a new block export. # +# Arguments describe a block export, i.e. how single node should be +# exported on an external interface. +# # Since: 5.2 ## { 'command': 'block-export-add', --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724151; cv=none; d=zohomail.com; s=zohoarc; b=Z8m2ehCzqQlPwDAZZTUQeEVR6giC+Y6TSdD3Mdrb4xU7Ir3cHWrNAT9NLWuIrBju/aWNbI09rFbNPfRFWsJNA6/V3N2c/9YNlMk+IqVOAS3FKGEMCE25V6NOk/E1hGmxHpOyNHvJNJdIJfNHUtP/ai+daGL9Fxk99h2wqtxL1uw= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724151; 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=3KJiwvwaCL+uNTf3ugR6KDZIQWXd/a4kqUtwiQfGVU0=; b=btHdaQ1VrrcruXpm1QTTqyXACBQeXJtQM4T1xPAB2dUhanoPETWyeKXE03hsxmcnIkpc3f/mm43j+//NfF+cmNwEiPmGIS7sbdHEvocFV+MRP7G/aYK5YSG7RKiP8syGjiqOVmAACfAsYaRkRD2ADCOW6OBaBDZb93MRV994fe8= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724151190249.6279497463886; Tue, 14 May 2024 15:02:31 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70Af-0005xO-0d; Tue, 14 May 2024 17:58:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70Ab-0005vk-Oh for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:49 -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 1s70Aa-0000Cs-7s for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:49 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-319-szDP95GjMkSmHdsHl0lvFQ-1; Tue, 14 May 2024 17:58:42 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id CAF6D81227E; Tue, 14 May 2024 21:58:41 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id E470E3C27; Tue, 14 May 2024 21:58:38 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723927; 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=3KJiwvwaCL+uNTf3ugR6KDZIQWXd/a4kqUtwiQfGVU0=; b=g0cUI0M3ReOCmfhw/WvU1ZtJ9+RoL5T7+Qn+7wAk4mb+T4oaLtI+oc4Ad0bgFD4NJ9o/zQ 6h252lxBM+kuKArx2my/jVi8cKOZi7o6+cS0G00XmakwpleAeuvCja855l6IdbVNboiox2 qnXlCctL1SrqNaoqLnqh7nOG0qTmHNk= X-MC-Unique: szDP95GjMkSmHdsHl0lvFQ-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 18/20] qapi: ensure all errors sections are uniformly typset Date: Tue, 14 May 2024 17:57:37 -0400 Message-ID: <20240514215740.940155-19-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724153231100003 Content-Type: text/plain; charset="utf-8" Transactions have the only instance of an Errors section that isn't a rST list; turn it into one. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/transaction.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/transaction.json b/qapi/transaction.json index 5749c133d4a..07afc269d54 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -235,7 +235,7 @@ # additional detail. # # Errors: -# Any errors from commands in the transaction +# - Any errors from commands in the transaction # # Note: The transaction aborts on the first failure. Therefore, there # will be information on only one failed operation returned in an --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724082; cv=none; d=zohomail.com; s=zohoarc; b=OoPdasZy7V31vewgzzwHilbPo6HmRo7IpI6G46odBq0Kp7utY3pp4iymjTPyrtXsAGK6h7Mokh6ZvPM0+wET2YXrVyCegyEc/tG2KvXEFcN1OL1h1pQ8NekpF1ct8IdZN3QafdXk7M2G4XZxAgAMw5yvbkszmLgD813bHFOi3T4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724082; 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=OZBGd6fiW8xge38vRYdkLfE1il5IsQP9PqdgnacboQw=; b=W4+Ft1ny/DehI2gAB2s5n7IjQrw52QylET+NgBuvh0yyCao5d24ZrKVeqsU14r5Ae+y03fMrf8Dju6elH315QqndslmNuRXLH4eM0ig6hg4JgiHs/BtEx6IpurfoBSSC/FE4zWP8seBBBVZvlqFCGbL/NyiZYd0QB9nIgACIvxQ= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724081995364.3712197779371; Tue, 14 May 2024 15:01:21 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70Ak-00067A-W0; Tue, 14 May 2024 17:58:59 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70Ag-000634-8Z for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:55 -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 1s70Ab-0000Dc-E9 for qemu-devel@nongnu.org; Tue, 14 May 2024 17:58:53 -0400 Received: from mimecast-mx02.redhat.com (mx-ext.redhat.com [66.187.233.73]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-662-5Te-TuokPdOYtAbIDbMmCQ-1; Tue, 14 May 2024 17:58:45 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id E76A63801ECE; Tue, 14 May 2024 21:58:44 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id E1DA06BC5; Tue, 14 May 2024 21:58:41 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723928; 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=OZBGd6fiW8xge38vRYdkLfE1il5IsQP9PqdgnacboQw=; b=MXfF9M+4xp5f94z2RvKDnjVNk9rpkopY6qTO4KkJQA76r1sX1s1haNX12kPq7pYnKDH63d 0vKj2BHI2X2qBYVvr8vJ0GQYBFvKEmx80FxuwA2rwkSU52NaUxu3PcEAFD3Qe8sX1MelFs OPBgyABL63fVyxvIm9MNp/kKq04L/pA= X-MC-Unique: 5Te-TuokPdOYtAbIDbMmCQ-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 19/20] qapi: convert "Note" sections to plain rST Date: Tue, 14 May 2024 17:57:38 -0400 Message-ID: <20240514215740.940155-20-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=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: 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: 1715724083042100003 Content-Type: text/plain; charset="utf-8" We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly. Update the QAPI parser to now prohibit special "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply: .. note:: lorem ipsum ... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs. These are rendered in orange: .. Attention:: ... .. Caution:: ... .. WARNING:: ... These are rendered in red: .. DANGER:: ... .. Error:: ... These are rendered in green: .. Hint:: ... .. Important:: ... .. Tip:: ... These are rendered in blue: .. Note:: ... .. admonition:: custom title admonition body text This patch uses ".. notes::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes. Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/block-core.json | 30 +++---- qapi/block.json | 2 +- qapi/char.json | 12 +-- qapi/control.json | 15 ++-- qapi/dump.json | 2 +- qapi/introspect.json | 6 +- qapi/machine-target.json | 26 +++--- qapi/machine.json | 47 +++++----- qapi/migration.json | 12 +-- qapi/misc.json | 88 +++++++++---------- qapi/net.json | 6 +- qapi/pci.json | 7 +- qapi/qdev.json | 30 +++---- qapi/qom.json | 19 ++-- qapi/rocker.json | 16 ++-- qapi/run-state.json | 18 ++-- qapi/sockets.json | 10 +-- qapi/stats.json | 22 ++--- qapi/transaction.json | 8 +- qapi/ui.json | 29 +++--- qapi/virtio.json | 12 +-- qga/qapi-schema.json | 48 +++++----- scripts/qapi/parser.py | 9 ++ tests/qapi-schema/doc-empty-section.err | 2 +- tests/qapi-schema/doc-empty-section.json | 2 +- tests/qapi-schema/doc-good.json | 6 +- tests/qapi-schema/doc-good.out | 10 ++- tests/qapi-schema/doc-good.txt | 14 ++- .../qapi-schema/doc-interleaved-section.json | 2 +- 29 files changed, 258 insertions(+), 252 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 64fe5240cc9..530af40404d 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1510,7 +1510,7 @@ # @mode: whether and how QEMU should create a new image, default is # 'absolute-paths'. # -# Note: Either @device or @node-name must be set but not both. +# .. note:: Either @device or @node-name must be set but not both. # ## { 'struct': 'BlockdevSnapshotSync', @@ -1616,9 +1616,9 @@ # # @unstable: Member @x-perf is experimental. # -# Note: @on-source-error and @on-target-error only affect background -# I/O. If an error occurs during a guest write request, the -# device's rerror/werror actions will be used. +# .. note:: @on-source-error and @on-target-error only affect background +# I/O. If an error occurs during a guest write request, the device's +# rerror/werror actions will be used. # # Since: 4.2 ## @@ -5534,8 +5534,8 @@ # after this event and must be repaired (Since 2.2; before, every # BLOCK_IMAGE_CORRUPTED event was fatal) # -# Note: If action is "stop", a STOP event will eventually follow the -# BLOCK_IO_ERROR event. +# .. note:: If action is "stop", a STOP event will eventually follow the +# BLOCK_IO_ERROR event. # # Example: # @@ -5581,8 +5581,8 @@ # field is a debugging aid for humans, it should not be parsed by # applications) (since: 2.2) # -# Note: If action is "stop", a STOP event will eventually follow the -# BLOCK_IO_ERROR event +# .. note:: If action is "stop", a STOP event will eventually follow the +# BLOCK_IO_ERROR event. # # Since: 0.13 # @@ -5720,8 +5720,8 @@ # # @speed: rate limit, bytes per second # -# Note: The "ready to complete" status is always reset by a -# @BLOCK_JOB_ERROR event +# .. note:: The "ready to complete" status is always reset by a +# @BLOCK_JOB_ERROR event. # # Since: 1.3 # @@ -5974,7 +5974,7 @@ # # @sectors-count: failed read operation sector count # -# Note: This event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 2.0 # @@ -6005,7 +6005,7 @@ # # @sectors-count: failed read operation sector count # -# Note: This event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 2.0 # @@ -6037,9 +6037,9 @@ # # @name: the name of the internal snapshot to be created # -# Notes: In transaction, if @name is empty, or any snapshot matching -# @name exists, the operation will fail. Only some image formats -# support it, for example, qcow2, and rbd. +# .. note:: In a transaction, if @name is empty or any snapshot matching +# @name exists, the operation will fail. Only some image formats +# support it; for example, qcow2, and rbd. # # Since: 1.7 ## diff --git a/qapi/block.json b/qapi/block.json index 5de99fe09d9..ea81d9e1921 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -113,7 +113,7 @@ # Errors: # - If @device is not a valid block device, DeviceNotFound # -# Notes: Ejecting a device with no media results in success +# .. note:: Ejecting a device with no media results in success. # # Since: 0.14 # diff --git a/qapi/char.json b/qapi/char.json index ab4c23976ed..0f39c2d5cdf 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -21,8 +21,8 @@ # backend (e.g. with the chardev=3D... option) is in open or closed # state (since 2.1) # -# Notes: @filename is encoded using the QEMU command line character -# device encoding. See the QEMU man page for details. +# .. note:: @filename is encoded using the QEMU command line character +# device encoding. See the QEMU man page for details. # # Since: 0.14 ## @@ -387,9 +387,9 @@ # # @rows: console height, in chars # -# Note: the options are only effective when the VNC or SDL graphical -# display backend is active. They are ignored with the GTK, -# Spice, VNC and D-Bus display backends. +# .. note:: The options are only effective when the VNC or SDL graphical +# display backend is active. They are ignored with the GTK, Spice, +# VNC and D-Bus display backends. # # Since: 1.5 ## @@ -805,7 +805,7 @@ # # @open: true if the guest has opened the virtio-serial port # -# Note: This event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 2.1 # diff --git a/qapi/control.json b/qapi/control.json index 10c906fa0e7..2498e5dd6ba 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -22,14 +22,13 @@ # "arguments": { "enable": [ "oob" ] } } # <- { "return": {} } # -# Notes: This command is valid exactly when first connecting: it must -# be issued before any other command will be accepted, and will -# fail once the monitor is accepting other commands. (see qemu -# docs/interop/qmp-spec.rst) +# .. note:: This command is valid exactly when first connecting: it must +# be issued before any other command will be accepted, and will fail +# once the monitor is accepting other commands. +# (see :doc:`/interop/qmp-spec`) # -# The QMP client needs to explicitly enable QMP capabilities, -# otherwise all the QMP capabilities will be turned off by -# default. +# .. note:: The QMP client needs to explicitly enable QMP capabilities, +# otherwise all the QMP capabilities will be turned off by default. # # Since: 0.13 ## @@ -150,7 +149,7 @@ # ] # } # -# Note: This example has been shortened as the real response is too +# Note: This example has been shortened as the real response is too # long. ## { 'command': 'query-commands', 'returns': ['CommandInfo'], diff --git a/qapi/dump.json b/qapi/dump.json index 2fa9504d864..f9aee7ea1dd 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -90,7 +90,7 @@ # and @length is not allowed to be specified with non-elf @format # at the same time (since 2.0) # -# Note: All boolean arguments default to false +# .. note:: All boolean arguments default to false. # # Since: 1.2 # diff --git a/qapi/introspect.json b/qapi/introspect.json index b041b02ba8c..b15052ec21a 100644 --- a/qapi/introspect.json +++ b/qapi/introspect.json @@ -41,9 +41,9 @@ # names are guaranteed to be unique (no name will be duplicated # with different meta-types). # -# Note: the QAPI schema is also used to help define *internal* -# interfaces, by defining QAPI types. These are not part of the -# QMP wire ABI, and therefore not returned by this command. +# .. note:: The QAPI schema is also used to help define *internal* +# interfaces, by defining QAPI types. These are not part of the QMP +# wire ABI, and therefore not returned by this command. # # Since: 2.5 ## diff --git a/qapi/machine-target.json b/qapi/machine-target.json index 29428530923..a8d9ec87f59 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -49,15 +49,15 @@ # to be migration-safe, but allows tooling to get an insight and # work with model details. # -# Note: When a non-migration-safe CPU model is expanded in static -# mode, some features enabled by the CPU model may be omitted, -# because they can't be implemented by a static CPU model -# definition (e.g. cache info passthrough and PMU passthrough in -# x86). If you need an accurate representation of the features -# enabled by a non-migration-safe CPU model, use @full. If you -# need a static representation that will keep ABI compatibility -# even when changing QEMU version or machine-type, use @static -# (but keep in mind that some features may be omitted). +# .. note:: When a non-migration-safe CPU model is expanded in static +# mode, some features enabled by the CPU model may be omitted, +# because they can't be implemented by a static CPU model definition +# (e.g. cache info passthrough and PMU passthrough in x86). If you +# need an accurate representation of the features enabled by a +# non-migration-safe CPU model, use @full. If you need a static +# representation that will keep ABI compatibility even when changing +# QEMU version or machine-type, use @static (but keep in mind that +# some features may be omitted). # # Since: 2.8 ## @@ -175,8 +175,8 @@ # - if a model contains an unknown cpu definition name, unknown # properties or properties with wrong types. # -# Note: this command isn't specific to s390x, but is only implemented -# on this architecture currently. +# .. note:: This command isn't specific to s390x, but is only +# implemented on this architecture currently. # # Since: 2.8 ## @@ -229,8 +229,8 @@ # - if a model contains an unknown cpu definition name, unknown # properties or properties with wrong types. # -# Note: this command isn't specific to s390x, but is only implemented -# on this architecture currently. +# .. note:: This command isn't specific to s390x, but is only +# implemented on this architecture currently. # # Since: 2.8 ## diff --git a/qapi/machine.json b/qapi/machine.json index 35cca12ba41..e9c9bef940d 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -24,9 +24,9 @@ # # @avr: since 5.1 # -# Notes: The resulting QMP strings can be appended to the -# "qemu-system-" prefix to produce the corresponding QEMU -# executable name. This is true even for "qemu-system-x86_64". +# .. note:: The resulting QMP strings can be appended to the +# "qemu-system-" prefix to produce the corresponding QEMU executable +# name. This is true even for "qemu-system-x86_64". # # Since: 3.0 ## @@ -305,8 +305,9 @@ # # Since: 0.14 # -# Notes: If no UUID was specified for the guest, a null UUID is -# returned. +# .. note:: If no UUID was specified for the guest, a null UUID is +# returned. +# ## { 'struct': 'UuidInfo', 'data': {'UUID': 'str'} } =20 @@ -367,10 +368,10 @@ # # Since: 0.14 # -# Notes: A guest may or may not respond to this command. This command -# returning does not indicate that a guest has accepted the -# request or that it has shut down. Many guests will respond to -# this command by prompting the user in some way. +# .. note:: A guest may or may not respond to this command. This +# command returning does not indicate that a guest has accepted the +# request or that it has shut down. Many guests will respond to this +# command by prompting the user in some way. # # Example: # @@ -389,8 +390,8 @@ # # Since: 1.1 # -# Note: prior to 4.0, this command does nothing in case the guest -# isn't suspended. +# .. note:: Prior to 4.0, this command does nothing in case the guest +# isn't suspended. # # Example: # @@ -440,8 +441,8 @@ # # Since: 0.14 # -# Note: prior to 2.1, this command was only supported for x86 and s390 -# VMs +# .. note:: Prior to 2.1, this command was only supported for x86 and +# s390 VMs # # Example: # @@ -838,7 +839,7 @@ # # Since: 0.14 # -# Notes: Errors were not reliably returned until 1.1 +# .. caution:: Errors were not reliably returned until 1.1. # # Example: # @@ -864,7 +865,7 @@ # # Since: 0.14 # -# Notes: Errors were not reliably returned until 1.1 +# .. caution:: Errors were not reliably returned until 1.1. # # Example: # @@ -994,8 +995,8 @@ # # @thread-id: thread number within the core the CPU belongs to # -# Note: management should be prepared to pass through additional -# properties with device_add. +# .. note:: Management should be prepared to pass through additional +# properties with device_add. # # Since: 2.7 ## @@ -1122,9 +1123,9 @@ # the KVM kernel module cannot support it, KVMMissingCap # - If no balloon device is present, DeviceNotActive # -# Notes: This command just issues a request to the guest. When it -# returns, the balloon size may not have changed. A guest can -# change the balloon size independent of this command. +# .. note:: This command just issues a request to the guest. When it +# returns, the balloon size may not have changed. A guest can change +# the balloon size independent of this command. # # Since: 0.14 # @@ -1184,7 +1185,7 @@ # @actual: the logical size of the VM in bytes Formula used: # logical_vm_size =3D vm_ram_size - balloon_size # -# Note: this event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 1.2 # @@ -1246,7 +1247,7 @@ # Emitted when the hv-balloon driver receives a "STATUS" message from # the guest. # -# Note: this event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 8.2 # @@ -1591,7 +1592,7 @@ # # @qom-path: path to the device object in the QOM tree (since 6.2) # -# Note: this event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 5.1 # diff --git a/qapi/migration.json b/qapi/migration.json index 89047d46c7c..a7b8ff138e3 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1428,8 +1428,8 @@ # # Cancel the current executing migration process. # -# Notes: This command succeeds even if there is no migration process -# running. +# .. note:: This command succeeds even if there is no migration process +# running. # # Since: 0.14 # @@ -1561,16 +1561,16 @@ # # Since: 0.14 # -# Notes: +# .. admonition:: Notes # # 1. The 'query-migrate' command should be used to check # migration's progress and final result (this information is # provided by the 'status' member) # -# 2. All boolean arguments default to false +# 2. All boolean arguments default to false. # # 3. The user Monitor's "detach" argument is invalid in QMP and -# should not be used +# should not be used. # # 4. The uri argument should have the Uniform Resource Identifier # of default destination VM. This connection will be bound to @@ -1644,7 +1644,7 @@ # # Since: 2.3 # -# Notes: +# .. admonition:: Notes # # 1. It's a bad idea to use a string for the uri, but it needs to # stay compatible with -incoming and the format of the uri is diff --git a/qapi/misc.json b/qapi/misc.json index 4b41e15dcd4..b04efbadec6 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -103,9 +103,9 @@ # # Returns a list of information about each iothread. # -# Note: this list excludes the QEMU main loop thread, which is not -# declared using the -object iothread command-line option. It is -# always the main thread of the process. +# .. note:: This list excludes the QEMU main loop thread, which is not +# declared using the ``-object iothread`` command-line option. It is +# always the main thread of the process. # # Returns: a list of @IOThreadInfo for each iothread # @@ -136,13 +136,13 @@ # # Since: 0.14 # -# Notes: This function will succeed even if the guest is already in -# the stopped state. In "inmigrate" state, it will ensure that -# the guest remains paused once migration finishes, as if the -S -# option was passed on the command line. +# .. note:: This function will succeed even if the guest is already in +# the stopped state. In "inmigrate" state, it will ensure that the +# guest remains paused once migration finishes, as if the ``-S`` +# option was passed on the command line. # -# In the "suspended" state, it will completely stop the VM and -# cause a transition to the "paused" state. (Since 9.0) +# In the "suspended" state, it will completely stop the VM and cause +# a transition to the "paused" state. (Since 9.0) # # Example: # @@ -158,15 +158,15 @@ # # Since: 0.14 # -# Notes: This command will succeed if the guest is currently running. -# It will also succeed if the guest is in the "inmigrate" state; -# in this case, the effect of the command is to make sure the -# guest starts once migration finishes, removing the effect of the -# -S command line option if it was passed. +# .. note:: This command will succeed if the guest is currently running. +# It will also succeed if the guest is in the "inmigrate" state; in +# this case, the effect of the command is to make sure the guest +# starts once migration finishes, removing the effect of the ``-S`` +# command line option if it was passed. # -# If the VM was previously suspended, and not been reset or woken, -# this command will transition back to the "suspended" state. -# (Since 9.0) +# If the VM was previously suspended, and not been reset or woken, +# this command will transition back to the "suspended" state. (Since +# 9.0) # # Example: # @@ -219,18 +219,18 @@ # # Since: 0.14 # -# Notes: This command only exists as a stop-gap. Its use is highly -# discouraged. The semantics of this command are not guaranteed: -# this means that command names, arguments and responses can -# change or be removed at ANY time. Applications that rely on -# long term stability guarantees should NOT use this command. +# .. note:: This command only exists as a stop-gap. Its use is highly +# discouraged. The semantics of this command are not guaranteed: +# this means that command names, arguments and responses can change +# or be removed at ANY time. Applications that rely on long term +# stability guarantees should NOT use this command. # -# Known limitations: +# Known limitations: # -# * This command is stateless, this means that commands that -# depend on state information (such as getfd) might not work +# * This command is stateless, this means that commands that +# depend on state information (such as getfd) might not work. # -# * Commands that prompt the user for data don't currently work +# * Commands that prompt the user for data don't currently work. # # Example: # @@ -252,11 +252,11 @@ # # Since: 0.14 # -# Notes: If @fdname already exists, the file descriptor assigned to it -# will be closed and replaced by the received file descriptor. +# .. note:: If @fdname already exists, the file descriptor assigned to +# it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file -# descriptor when it is no longer needed. +# The 'closefd' command can be used to explicitly close the file +# descriptor when it is no longer needed. # # Example: # @@ -279,11 +279,11 @@ # # Since: 8.0 # -# Notes: If @fdname already exists, the file descriptor assigned to it -# will be closed and replaced by the received file descriptor. +# .. note:: If @fdname already exists, the file descriptor assigned to +# it will be closed and replaced by the received file descriptor. # -# The 'closefd' command can be used to explicitly close the file -# descriptor when it is no longer needed. +# The 'closefd' command can be used to explicitly close the file +# descriptor when it is no longer needed. # # Example: # @@ -339,10 +339,9 @@ # - If file descriptor was not received, GenericError # - If @fdset-id is a negative value, GenericError # -# Notes: -# The list of fd sets is shared by all monitor connections. +# .. note:: The list of fd sets is shared by all monitor connections. # -# If @fdset-id is not specified, a new fd set will be created. +# .. note:: If @fdset-id is not specified, a new fd set will be created. # # Since: 1.2 # @@ -370,11 +369,10 @@ # # Since: 1.2 # -# Notes: -# The list of fd sets is shared by all monitor connections. +# .. note:: The list of fd sets is shared by all monitor connections. # -# If @fd is not specified, all file descriptors in @fdset-id will -# be removed. +# .. note:: If @fd is not specified, all file descriptors in @fdset-id +# will be removed. # # Example: # @@ -420,7 +418,7 @@ # # Since: 1.2 # -# Note: The list of fd sets is shared by all monitor connections. +# .. note:: The list of fd sets is shared by all monitor connections. # # Example: # @@ -561,9 +559,9 @@ # # @qom-path: path to the RTC object in the QOM tree # -# Note: This event is rate-limited. It is not guaranteed that the RTC -# in the system implements this event, or even that the system has -# an RTC at all. +# .. note:: This event is rate-limited. It is not guaranteed that the +# RTC in the system implements this event, or even that the system +# has an RTC at all. # # Since: 0.13 # diff --git a/qapi/net.json b/qapi/net.json index dc616d010f0..4ac7fdc7e6c 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -22,9 +22,9 @@ # # Since: 0.14 # -# Notes: Not all network adapters support setting link status. This -# command will succeed even if the network adapter does not -# support link status notification. +# .. note:: Not all network adapters support setting link status. This +# command will succeed even if the network adapter does not support +# link status notification. # # Example: # diff --git a/qapi/pci.json b/qapi/pci.json index 08bf6958634..f51159a2c4c 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -146,8 +146,8 @@ # # @regions: a list of the PCI I/O regions associated with the device # -# Notes: the contents of @class_info.desc are not stable and should -# only be treated as informational. +# .. note:: The contents of @class_info.desc are not stable and should +# only be treated as informational. # # Since: 0.14 ## @@ -311,7 +311,8 @@ # ] # } # -# Note: This example has been shortened as the real response is too +# Note: This example has been shortened as the real response is too # long. +# ## { 'command': 'query-pci', 'returns': ['PciInfo'] } diff --git a/qapi/qdev.json b/qapi/qdev.json index facaa0bc6a2..d031fc3590d 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -20,9 +20,9 @@ # Returns: a list of ObjectPropertyInfo describing a devices # properties # -# Note: objects can create properties at runtime, for example to -# describe links between different devices and/or objects. These -# properties are not included in the output of this command. +# .. note:: Objects can create properties at runtime, for example to +# describe links between different devices and/or objects. These +# properties are not included in the output of this command. # # Since: 1.2 ## @@ -51,7 +51,7 @@ # supports JSON syntax without the reference counting leak that # broke hot-unplug # -# Notes: +# .. admonition:: Notes # # 1. Additional arguments depend on the type. # @@ -59,8 +59,8 @@ # the 'docs/qdev-device-use.txt' file. # # 3. It's possible to list device properties by running QEMU with -# the "-device DEVICE,help" command-line argument, where DEVICE -# is the device's name +# the ``-device DEVICE,help`` command-line argument, where DEVICE +# is the device's name. # # Example: # @@ -92,15 +92,15 @@ # Errors: # - If @id is not a valid device, DeviceNotFound # -# Notes: When this command completes, the device may not be removed -# from the guest. Hot removal is an operation that requires guest -# cooperation. This command merely requests that the guest begin -# the hot removal process. Completion of the device removal -# process is signaled with a DEVICE_DELETED event. Guest reset -# will automatically complete removal for all devices. If a -# guest-side error in the hot removal process is detected, the -# device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event -# is sent. Some errors cannot be detected. +# .. note:: When this command completes, the device may not be removed +# from the guest. Hot removal is an operation that requires guest +# cooperation. This command merely requests that the guest begin the +# hot removal process. Completion of the device removal process is +# signaled with a DEVICE_DELETED event. Guest reset will +# automatically complete removal for all devices. If a guest-side +# error in the hot removal process is detected, the device will not +# be removed and a DEVICE_UNPLUG_GUEST_ERROR event is sent. Some +# errors cannot be detected. # # Since: 0.14 # diff --git a/qapi/qom.json b/qapi/qom.json index 8f0601859b1..e927f4a3c5d 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -195,12 +195,12 @@ # # @typename: the type name of an object # -# Note: objects can create properties at runtime, for example to -# describe links between different devices and/or objects. These -# properties are not included in the output of this command. -# # Returns: a list of ObjectPropertyInfo describing object properties # +# .. note:: Objects can create properties at runtime, for example to +# describe links between different devices and/or objects. These +# properties are not included in the output of this command. +# # Since: 2.12 ## { 'command': 'qom-list-properties', @@ -608,12 +608,11 @@ # older to allow migration with newer QEMU versions. # (default: false generally, but true for machine types <=3D 4.0) # -# Note: prealloc=3Dtrue and reserve=3Dfalse cannot be set at the same -# time. With reserve=3Dtrue, the behavior depends on the operating -# system: for example, Linux will not reserve swap space for -# shared file mappings -- "not applicable". In contrast, -# reserve=3Dfalse will bail out if it cannot be configured -# accordingly. +# .. note:: prealloc=3Dtrue and reserve=3Dfalse cannot be set at the same +# time. With reserve=3Dtrue, the behavior depends on the operating +# system: for example, Linux will not reserve swap space for shared +# file mappings -- "not applicable". In contrast, reserve=3Dfalse will +# bail out if it cannot be configured accordingly. # # Since: 2.1 ## diff --git a/qapi/rocker.json b/qapi/rocker.json index f5225eb62cc..9f95e638309 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -138,8 +138,8 @@ # # @ip-dst: IP header destination address # -# Note: optional members may or may not appear in the flow key -# depending if they're relevant to the flow key. +# .. note:: Optional members may or may not appear in the flow key +# depending if they're relevant to the flow key. # # Since: 2.4 ## @@ -168,8 +168,8 @@ # # @ip-tos: IP header TOS field # -# Note: optional members may or may not appear in the flow mask -# depending if they're relevant to the flow mask. +# .. note:: Optional members may or may not appear in the flow mask +# depending if they're relevant to the flow mask. # # Since: 2.4 ## @@ -195,8 +195,8 @@ # # @out-pport: physical output port # -# Note: optional members may or may not appear in the flow action -# depending if they're relevant to the flow action. +# .. note:: Optional members may or may not appear in the flow action +# depending if they're relevant to the flow action. # # Since: 2.4 ## @@ -288,8 +288,8 @@ # # @ttl-check: perform TTL check # -# Note: optional members may or may not appear in the group depending -# if they're relevant to the group type. +# .. note:: Optional members may or may not appear in the group depending +# if they're relevant to the group type. # # Since: 2.4 ## diff --git a/qapi/run-state.json b/qapi/run-state.json index f8773f23b29..252d7d6afa7 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -146,9 +146,9 @@ # @reason: The @ShutdownCause which resulted in the SHUTDOWN. # (since 4.0) # -# Note: If the command-line option "-no-shutdown" has been specified, -# qemu will not exit, and a STOP event will eventually follow the -# SHUTDOWN event +# .. note:: If the command-line option ``-no-shutdown`` has been +# specified, qemu will not exit, and a STOP event will eventually +# follow the SHUTDOWN event. # # Since: 0.12 # @@ -247,8 +247,8 @@ # saved on disk, for example, S4 state, which is sometimes called # hibernate state # -# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering -# this state +# .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering +# this state. # # Since: 1.2 # @@ -281,11 +281,11 @@ # # @action: action that has been taken # -# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG -# event is followed respectively by the RESET, SHUTDOWN, or STOP -# events +# .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG +# event is followed respectively by the RESET, SHUTDOWN, or STOP +# events. # -# Note: This event is rate-limited. +# .. note:: This event is rate-limited. # # Since: 0.13 # diff --git a/qapi/sockets.json b/qapi/sockets.json index aa97c897687..f46113ab1b8 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -104,8 +104,8 @@ # # @port: port # -# Note: string types are used to allow for possible future hostname or -# service resolution support. +# .. note:: string types are used to allow for possible future hostname +# or service resolution support. # # Since: 2.8 ## @@ -179,9 +179,9 @@ # # @type: Transport type # -# Note: This type is deprecated in favor of SocketAddress. The -# difference between SocketAddressLegacy and SocketAddress is that -# the latter has fewer {} on the wire. +# .. note:: This type is deprecated in favor of SocketAddress. The +# difference between SocketAddressLegacy and SocketAddress is that +# the latter has fewer ``{}`` on the wire. # # Since: 1.3 ## diff --git a/qapi/stats.json b/qapi/stats.json index c4a9f3ff70e..683929b2322 100644 --- a/qapi/stats.json +++ b/qapi/stats.json @@ -254,17 +254,17 @@ # # @provider: a provider to restrict the query to. # -# Note: runtime-collected statistics and their names fall outside -# QEMU's usual deprecation policies. QEMU will try to keep the -# set of available data stable, together with their names, but -# will not guarantee stability at all costs; the same is true of -# providers that source statistics externally, e.g. from Linux. -# For example, if the same value is being tracked with different -# names on different architectures or by different providers, one -# of them might be renamed. A statistic might go away if an -# algorithm is changed or some code is removed; changing a default -# might cause previously useful statistics to always report 0. -# Such changes, however, are expected to be rare. +# .. note:: runtime-collected statistics and their names fall outside +# QEMU's usual deprecation policies. QEMU will try to keep the set +# of available data stable, together with their names, but will not +# guarantee stability at all costs; the same is true of providers +# that source statistics externally, e.g. from Linux. For example, +# if the same value is being tracked with different names on +# different architectures or by different providers, one of them +# might be renamed. A statistic might go away if an algorithm is +# changed or some code is removed; changing a default might cause +# previously useful statistics to always report 0. Such changes, +# however, are expected to be rare. # # Since: 7.1 ## diff --git a/qapi/transaction.json b/qapi/transaction.json index 07afc269d54..bcb05fdedd6 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -237,10 +237,10 @@ # Errors: # - Any errors from commands in the transaction # -# Note: The transaction aborts on the first failure. Therefore, there -# will be information on only one failed operation returned in an -# error condition, and subsequent actions will not have been -# attempted. +# .. note:: The transaction aborts on the first failure. Therefore, +# there will be information on only one failed operation returned in +# an error condition, and subsequent actions will not have been +# attempted. # # Since: 1.1 # diff --git a/qapi/ui.json b/qapi/ui.json index 2d0aa407aca..ec72998e28e 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -103,11 +103,10 @@ # - '+INT' where INT is the number of seconds from now (integer) # - 'INT' where INT is the absolute time in seconds # -# Notes: Time is relative to the server and currently there is no way -# to coordinate server time with client time. It is not -# recommended to use the absolute time version of the @time -# parameter unless you're sure you are on the same machine as the -# QEMU instance. +# .. note:: Time is relative to the server and currently there is no way +# to coordinate server time with client time. It is not recommended +# to use the absolute time version of the @time parameter unless +# you're sure you are on the same machine as the QEMU instance. # # Since: 7.0 ## @@ -268,7 +267,7 @@ # @unknown: No information is available about mouse mode used by the # spice server. # -# Note: spice/enums.h has a SpiceMouseMode already, hence the name. +# .. note:: spice/enums.h has a SpiceMouseMode already, hence the name. # # Since: 1.1 ## @@ -697,9 +696,9 @@ # # Since: 1.1 # -# Notes: An empty password in this command will set the password to -# the empty string. Existing clients are unaffected by executing -# this command. +# .. note:: An empty password in this command will set the password to +# the empty string. Existing clients are unaffected by executing +# this command. ## { 'command': 'change-vnc-password', 'data': { 'password': 'str' }, @@ -714,8 +713,8 @@ # # @client: client information # -# Note: This event is emitted before any authentication takes place, -# thus the authentication ID is not provided +# .. note:: This event is emitted before any authentication takes place, +# thus the authentication ID is not provided. # # Since: 0.13 # @@ -1260,10 +1259,10 @@ # # Since: 2.6 # -# Note: The consoles are visible in the qom tree, under -# /backend/console[$index]. They have a device link and head -# property, so it is possible to map which console belongs to -# which device and display. +# .. note:: The consoles are visible in the qom tree, under +# ``/backend/console[$index]``. They have a device link and head +# property, so it is possible to map which console belongs to which +# device and display. # # Examples: # diff --git a/qapi/virtio.json b/qapi/virtio.json index 74fc27c7029..b91f3cdd0df 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -559,12 +559,12 @@ # # Returns: VirtQueueStatus of the VirtQueue # -# Notes: last_avail_idx will not be displayed in the case where the -# selected VirtIODevice has a running vhost device and the -# VirtIODevice VirtQueue index (queue) does not exist for the -# corresponding vhost device vhost_virtqueue. Also, -# shadow_avail_idx will not be displayed in the case where the -# selected VirtIODevice has a running vhost device. +# .. note:: last_avail_idx will not be displayed in the case where the +# selected VirtIODevice has a running vhost device and the +# VirtIODevice VirtQueue index (queue) does not exist for the +# corresponding vhost device vhost_virtqueue. Also, shadow_avail_idx +# will not be displayed in the case where the selected VirtIODevice +# has a running vhost device. # # Since: 7.2 # diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index b3de1fb6b3a..1273d85bb5f 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -422,8 +422,9 @@ # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined # below) # -# Note: This may fail to properly report the current state as a result -# of some other guest processes having issued an fs freeze/thaw. +# .. note:: This may fail to properly report the current state as a +# result of some other guest processes having issued an fs +# freeze/thaw. # # Since: 0.15.0 ## @@ -443,9 +444,9 @@ # # Returns: Number of file systems currently frozen. # -# Note: On Windows, the command is implemented with the help of a -# Volume Shadow-copy Service DLL helper. The frozen state is -# limited for up to 10 seconds by VSS. +# .. note:: On Windows, the command is implemented with the help of a +# Volume Shadow-copy Service DLL helper. The frozen state is limited +# for up to 10 seconds by VSS. # # Since: 0.15.0 ## @@ -479,10 +480,10 @@ # # Returns: Number of file systems thawed by this call # -# Note: if return value does not match the previous call to -# guest-fsfreeze-freeze, this likely means some freezable -# filesystems were unfrozen before this call, and that the -# filesystem state may have changed before issuing this command. +# .. note:: If the return value does not match the previous call to +# guest-fsfreeze-freeze, this likely means some freezable filesystems +# were unfrozen before this call, and that the filesystem state may +# have changed before issuing this command. # # Since: 0.15.0 ## @@ -560,8 +561,8 @@ # Errors: # - If suspend to disk is not supported, Unsupported # -# Notes: It's strongly recommended to issue the guest-sync command -# before sending commands when the guest resumes +# .. note:: It's strongly recommended to issue the guest-sync command +# before sending commands when the guest resumes. # # Since: 1.1 ## @@ -596,8 +597,8 @@ # Errors: # - If suspend to ram is not supported, Unsupported # -# Notes: It's strongly recommended to issue the guest-sync command -# before sending commands when the guest resumes +# .. note:: It's strongly recommended to issue the guest-sync command +# before sending commands when the guest resumes. # # Since: 1.1 ## @@ -631,8 +632,8 @@ # Errors: # - If hybrid suspend is not supported, Unsupported # -# Notes: It's strongly recommended to issue the guest-sync command -# before sending commands when the guest resumes +# .. note:: It's strongly recommended to issue the guest-sync command +# before sending commands when the guest resumes. # # Since: 1.1 ## @@ -1461,16 +1462,15 @@ # * POSIX: as defined by os-release(5) # * Windows: contains string "server" or "client" # -# Notes: On POSIX systems the fields @id, @name, @pretty-name, -# @version, @version-id, @variant and @variant-id follow the -# definition specified in os-release(5). Refer to the manual page -# for exact description of the fields. Their values are taken -# from the os-release file. If the file is not present in the -# system, or the values are not present in the file, the fields -# are not included. +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, +# @version, @version-id, @variant and @variant-id follow the +# definition specified in os-release(5). Refer to the manual page for +# exact description of the fields. Their values are taken from the +# os-release file. If the file is not present in the system, or the +# values are not present in the file, the fields are not included. # -# On Windows the values are filled from information gathered from -# the system. +# On Windows the values are filled from information gathered from +# the system. # # Since: 2.10 ## diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 3cd8e7ee295..8b1da96124e 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -557,6 +557,15 @@ def get_doc(self) -> 'QAPIDoc': r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', line): # tagged section + + if 'Note' in match.group(1): + emsg =3D ( + f"The '{match.group(1)}' section is deprecated= ." + " Please use rST's '.. note::' directive or " + "another suitable admonition instead." + ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text =3D line[match.end():] if text: diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/do= c-empty-section.err index 5f03a6d733f..711a0d629c2 100644 --- a/tests/qapi-schema/doc-empty-section.err +++ b/tests/qapi-schema/doc-empty-section.err @@ -1 +1 @@ -doc-empty-section.json:6: text required after 'Note:' +doc-empty-section.json:6: text required after 'Errors:' diff --git a/tests/qapi-schema/doc-empty-section.json b/tests/qapi-schema/d= oc-empty-section.json index f3384e9a3bb..f179d3eff6d 100644 --- a/tests/qapi-schema/doc-empty-section.json +++ b/tests/qapi-schema/doc-empty-section.json @@ -3,6 +3,6 @@ ## # @foo: # -# Note: +# Errors: ## { 'command': 'foo', 'data': {'a': 'int'} } diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son index de38a386e8f..0a294eb324e 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -29,7 +29,7 @@ # - Second list # Note: still in list # -# Note: not in list +# .. note:: not in list # # 1. Third list # is numbered @@ -155,7 +155,7 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Note: @arg3 is undocumented +# .. note:: @arg3 is undocumented # # Returns: @Object # @@ -163,7 +163,7 @@ # # TODO: frobnicate # -# Notes: +# .. admonition:: Notes # # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 435f6e6d768..2c9b4e419cb 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -76,7 +76,7 @@ Not in list - Second list Note: still in list =20 -Note: not in list +.. note:: not in list =20 1. Third list is numbered @@ -169,15 +169,17 @@ description starts on the same line a feature feature=3Dcmd-feat2 another feature - section=3DNote -@arg3 is undocumented + section=3DNone +.. note:: @arg3 is undocumented section=3DReturns @Object section=3DErrors some section=3DTODO frobnicate - section=3DNotes + section=3DNone +.. admonition:: Notes + - Lorem ipsum dolor sit amet - Ut enim ad minim veniam =20 diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 847db70412d..b89f35d5476 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -17,7 +17,9 @@ Not in list =20 * Second list Note: still in list =20 -Note: not in list +Note: + + not in list =20 1. Third list is numbered =20 @@ -193,11 +195,9 @@ Features "cmd-feat2" another feature =20 +Note: =20 -Note -~~~~ - -"arg3" is undocumented + "arg3" is undocumented =20 =20 Returns @@ -211,9 +211,7 @@ Errors =20 some =20 - -Notes -~~~~~ +Notes: =20 * Lorem ipsum dolor sit amet =20 diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-sc= hema/doc-interleaved-section.json index adb29e98daa..b26bc0bbb79 100644 --- a/tests/qapi-schema/doc-interleaved-section.json +++ b/tests/qapi-schema/doc-interleaved-section.json @@ -10,7 +10,7 @@ # # bao # -# Note: a section. +# Returns: a section. # # @foobar: catch this # --=20 2.44.0 From nobody Mon Nov 25 09:21:17 2024 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=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1715724097; cv=none; d=zohomail.com; s=zohoarc; b=lDlw37j9W5iCdxtQa8MWGBJCNBdJxS5qzotFE+LHFm9aiMHRZRed3z9VuwYLK+Yx7l6yxBj6tl1XfddyzZ9uB7VrPUlnCWNjtSujQplg90z8hDnsxuju+qoyMMdfrKHgLeT1l5w/IITuKlB9GhmgaS40r6rkfCG0fUESv0v42Mo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1715724097; 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=h3yJeumY1ZGhqd9zHhlMiVKODqIPkJOpbqIauLtEQqs=; b=O2EU1swW2QPgw6+awenxFlXJ4Zpu+xLQCSDDqgKnygeL//IRSZV//ewMuKUM+7rWFvW5gjzdKqneFKz9wq+8ykR7msYSlXG6h7virBxyQWko0gqUBzkjosUnMeVuYvgmG1Ud/PBbnIevtWcyvYj9b5kqbzleziSvOSnt547b9/M= 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=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1715724097568780.0707454920034; Tue, 14 May 2024 15:01:37 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1s70B4-0006d9-Jq; Tue, 14 May 2024 17:59:18 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1s70As-0006H7-BQ for qemu-devel@nongnu.org; Tue, 14 May 2024 17:59:12 -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 1s70An-0000Fe-Lt for qemu-devel@nongnu.org; Tue, 14 May 2024 17:59:05 -0400 Received: from mimecast-mx02.redhat.com (mimecast-mx02.redhat.com [66.187.233.88]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-132-xUyHT0r1NXat8kxQAyjOSA-1; Tue, 14 May 2024 17:58:49 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.rdu2.redhat.com [10.11.54.1]) (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 mimecast-mx02.redhat.com (Postfix) with ESMTPS id 03316805965; Tue, 14 May 2024 21:58:48 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.17.156]) by smtp.corp.redhat.com (Postfix) with ESMTP id 09B3E3C27; Tue, 14 May 2024 21:58:45 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1715723941; 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=h3yJeumY1ZGhqd9zHhlMiVKODqIPkJOpbqIauLtEQqs=; b=OW+Jyzf1K+GXLFDv9tXSdUzWgS41JPoBE///72CNFymAao1eNQPZ3Jo9FBv1fCW+jHr62x eZmUXeOs1Bs9pY70guU3bRJAtgMrpoWjIED4b4Aap72F9r1qXbC6AtiObtTI4PxFakc4sP cwHdMftszAWiCWYgX8TGbmuuhU6h/hE= X-MC-Unique: xUyHT0r1NXat8kxQAyjOSA-1 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Xu , Marcel Apfelbaum , Gerd Hoffmann , Fabiano Rosas , Pavel Dovgalyuk , Markus Armbruster , Ani Sinha , Michael Roth , Kevin Wolf , Jiri Pirko , Mads Ynddal , Jason Wang , Igor Mammedov , Peter Maydell , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Stefan Hajnoczi , Paolo Bonzini , Eduardo Habkost , "Michael S. Tsirkin" , qemu-block@nongnu.org, Stefan Berger , Victor Toso de Carvalho , Eric Blake , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Konstantin Kostiuk , Lukas Straub , Yanan Wang , Hanna Reitz , John Snow Subject: [PATCH 20/20] qapi: convert "Example" sections to rST Date: Tue, 14 May 2024 17:57:39 -0400 Message-ID: <20240514215740.940155-21-jsnow@redhat.com> In-Reply-To: <20240514215740.940155-1-jsnow@redhat.com> References: <20240514215740.940155-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.11.54.1 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=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -30 X-Spam_score: -3.1 X-Spam_bar: --- X-Spam_report: (-3.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.974, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=unavailable autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: 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: 1715724099142100005 Content-Type: text/plain; charset="utf-8" Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines. This patch does also allow for the use of the rST syntax "Example::" by exempting double-colon syntax from the QAPI doc parser, but that form is not used by this conversion patch. The phrase "Example" here is not special, it is the double-colon syntax that transforms the following block into a code-block. By default, *this* form does not apply QMP highlighting. This patch has several benefits: 1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired. 2. Example sections can now use fully arbitrary rST. 3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets. 4. Each code-block can be captioned independently without bypassing the QMP lexer/validator. For any sections with more than one example, examples are split up into multiple code-block regions. If annotations are present, those annotations are converted into code-block captions instead, e.g. ``` Examples: 1. Lorem Ipsum -> { "foo": "bar" } ``` Is rewritten as: ``` .. code-block:: QMP :caption: Example: Lorem Ipsum -> { "foo": "bar" } ``` This process was only semi-automated: 1. Replace "Examples?:" sections with sed: sed -i 's|# Example:|# .. code-block:: QMP|' *.json sed -i 's|# Examples:|# .. code-block:: QMP|' *.json 2. Identify sections that no longer parse successfully by attempting the doc build, convert annotations into captions manually. (Tedious, oh well.) 3. Add captions where still needed: sed -zi 's|# .. code-block:: QMP\n#\n|# .. code-block:: QMP\n# :caption:= Example\n#\n|g' *.json Not fully ideal, but hopefully not something that has to be done very often. (Or ever again.) Signed-off-by: John Snow Acked-by: Stefan Hajnoczi --- qapi/acpi.json | 6 +- qapi/block-core.json | 120 ++++++++++++++++---------- qapi/block.json | 60 +++++++------ qapi/char.json | 36 ++++++-- qapi/control.json | 16 ++-- qapi/dump.json | 12 ++- qapi/machine-target.json | 3 +- qapi/machine.json | 79 ++++++++++------- qapi/migration.json | 145 +++++++++++++++++++++++--------- qapi/misc-target.json | 33 +++++--- qapi/misc.json | 48 +++++++---- qapi/net.json | 30 +++++-- qapi/pci.json | 6 +- qapi/qapi-schema.json | 6 +- qapi/qdev.json | 15 +++- qapi/qom.json | 20 +++-- qapi/replay.json | 12 ++- qapi/rocker.json | 12 ++- qapi/run-state.json | 45 ++++++---- qapi/tpm.json | 9 +- qapi/trace.json | 6 +- qapi/transaction.json | 3 +- qapi/ui.json | 62 +++++++++----- qapi/virtio.json | 38 +++++---- qapi/yank.json | 6 +- scripts/qapi/parser.py | 15 +++- tests/qapi-schema/doc-good.json | 12 +-- tests/qapi-schema/doc-good.out | 17 ++-- tests/qapi-schema/doc-good.txt | 17 +--- 29 files changed, 574 insertions(+), 315 deletions(-) diff --git a/qapi/acpi.json b/qapi/acpi.json index aa4dbe57943..3da01f1b7fc 100644 --- a/qapi/acpi.json +++ b/qapi/acpi.json @@ -111,7 +111,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-acpi-ospm-status" } # <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM",= "source": 1, "status": 0}, @@ -131,7 +132,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "ACPI_DEVICE_OST", # "data": { "info": { "device": "d1", "slot": "0", diff --git a/qapi/block-core.json b/qapi/block-core.json index 530af40404d..bb0447207df 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -763,7 +763,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-block" } # <- { @@ -1167,7 +1168,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-blockstats" } # <- { @@ -1460,7 +1462,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block_resize", # "arguments": { "device": "scratch", "size": 1073741824 } } @@ -1678,7 +1681,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-snapshot-sync", # "arguments": { "device": "ide-hd0", @@ -1711,7 +1715,8 @@ # # Since: 2.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-add", # "arguments": { "driver": "qcow2", @@ -1857,7 +1862,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-commit", # "arguments": { "device": "virtio0", @@ -1895,7 +1901,8 @@ # # Since: 1.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "drive-backup", # "arguments": { "device": "drive0", @@ -1921,7 +1928,8 @@ # # Since: 2.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-backup", # "arguments": { "device": "src-id", @@ -1945,7 +1953,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-named-block-nodes" } # <- { "return": [ { "ro":false, @@ -2126,7 +2135,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "drive-mirror", # "arguments": { "device": "ide-hd0", @@ -2302,7 +2312,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-add", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2326,7 +2337,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-remove", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2349,7 +2361,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-clear", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2370,7 +2383,8 @@ # # Since: 4.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-enable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2391,7 +2405,8 @@ # # Since: 4.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-disable", # "arguments": { "node": "drive0", "name": "bitmap0" } } @@ -2423,7 +2438,8 @@ # # Since: 4.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-dirty-bitmap-merge", # "arguments": { "node": "drive0", "target": "bitmap0", @@ -2532,7 +2548,8 @@ # # Since: 2.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-mirror", # "arguments": { "device": "ide-hd0", @@ -2856,7 +2873,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-stream", # "arguments": { "device": "virtio0", @@ -4790,7 +4808,8 @@ # # Since: 2.9 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-add", # "arguments": { @@ -4804,6 +4823,9 @@ # } # <- { "return": {} } # +# .. code-block:: QMP +# :caption: Example +# # -> { "execute": "blockdev-add", # "arguments": { # "driver": "qcow2", @@ -4888,7 +4910,8 @@ # # Since: 2.9 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-add", # "arguments": { @@ -5537,7 +5560,8 @@ # .. note:: If action is "stop", a STOP event will eventually follow the # BLOCK_IO_ERROR event. # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "", "node-name": "drive", "fatal": false, @@ -5586,7 +5610,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_IO_ERROR", # "data": { "device": "ide0-hd1", @@ -5626,7 +5651,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_JOB_COMPLETED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5661,7 +5687,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_JOB_CANCELLED", # "data": { "type": "stream", "device": "virtio-disk0", @@ -5690,7 +5717,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_JOB_ERROR", # "data": { "device": "ide0-hd1", @@ -5725,7 +5753,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_JOB_READY", # "data": { "device": "drive0", "type": "mirror", "speed": 0, @@ -5753,7 +5782,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BLOCK_JOB_PENDING", # "data": { "type": "mirror", "id": "backup_1" }, @@ -5827,7 +5857,8 @@ # # Since: 2.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block-set-write-threshold", # "arguments": { "node-name": "mydev", @@ -5872,9 +5903,8 @@ # # Since: 2.7 # -# Examples: -# -# 1. Add a new node to a quorum +# .. code-block:: QMP +# :caption: Example: Add a new node to a quorum # # -> { "execute": "blockdev-add", # "arguments": { @@ -5888,7 +5918,8 @@ # "node": "new_node" } } # <- { "return": {} } # -# 2. Delete a quorum's node +# .. code-block:: QMP +# :caption: Example: Delete a quorum's node # # -> { "execute": "x-blockdev-change", # "arguments": { "parent": "disk1", @@ -5924,16 +5955,16 @@ # # Since: 2.12 # -# Examples: -# -# 1. Move a node into an IOThread +# .. code-block:: QMP +# :caption: Example: Move a node into an IOThread # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", # "iothread": "iothread0" } } # <- { "return": {} } # -# 2. Move a node into the main loop +# .. code-block:: QMP +# :caption: Example: Move a node into the main loop # # -> { "execute": "x-blockdev-set-iothread", # "arguments": { "node-name": "disk1", @@ -5978,7 +6009,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "QUORUM_FAILURE", # "data": { "reference": "usr1", "sector-num": 345435, "sectors-c= ount": 5 }, @@ -6009,16 +6041,16 @@ # # Since: 2.0 # -# Examples: -# -# 1. Read operation +# .. code-block:: QMP +# :caption: Example: Read operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 345435, "sectors-= count": 5, # "type": "read" }, # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } # -# 2. Flush operation +# .. code-block:: QMP +# :caption: Example: Flush operation # # <- { "event": "QUORUM_REPORT_BAD", # "data": { "node-name": "node0", "sector-num": 0, "sectors-count= ": 2097120, @@ -6066,7 +6098,8 @@ # # Since: 1.7 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-snapshot-internal-sync", # "arguments": { "device": "ide-hd0", @@ -6105,7 +6138,8 @@ # # Since: 1.7 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-snapshot-delete-internal-sync", # "arguments": { "device": "ide-hd0", diff --git a/qapi/block.json b/qapi/block.json index ea81d9e1921..c67bda708a2 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -117,7 +117,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } } # <- { "return": {} } @@ -161,7 +162,8 @@ # # Since: 2.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-open-tray", # "arguments": { "id": "ide0-1-0" } } @@ -199,7 +201,8 @@ # # Since: 2.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-close-tray", # "arguments": { "id": "ide0-1-0" } } @@ -231,7 +234,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-remove-medium", # "arguments": { "id": "ide0-1-0" } } @@ -272,7 +276,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "blockdev-add", # "arguments": { @@ -342,9 +347,8 @@ # # Since: 2.5 # -# Examples: -# -# 1. Change a removable medium +# .. code-block:: QMP +# :caption: Example: Change a removable medium # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "ide0-1-0", @@ -352,7 +356,8 @@ # "format": "raw" } } # <- { "return": {} } # -# 2. Load a read-only medium into a writable drive +# .. code-block:: QMP +# :caption: Example: Load a read-only medium into a writable drive # # -> { "execute": "blockdev-change-medium", # "arguments": { "id": "floppyA", @@ -397,7 +402,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "DEVICE_TRAY_MOVED", # "data": { "device": "ide1-cd0", @@ -421,7 +427,8 @@ # # Since: 3.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "PR_MANAGER_STATUS_CHANGED", # "data": { "id": "pr-helper0", @@ -463,7 +470,8 @@ # # Since: 1.1 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "virtio-blk-pci0/virtio-backend", @@ -483,6 +491,9 @@ # "iops_size": 0 } } # <- { "return": {} } # +# .. code-block:: QMP +# :caption: Example +# # -> { "execute": "block_set_io_throttle", # "arguments": { "id": "ide0-1-0", # "bps": 1000000, @@ -543,29 +554,27 @@ # # Since: 4.0 # -# Example: -# -# Set new histograms for all io types with intervals -# [0, 10), [10, 50), [50, 100), [100, +inf): +# .. code-block:: QMP +# :caption: Example: +# Set new histograms for all io types with intervals +# [0, 10), [10, 50), [50, 100), [100, +inf): # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries": [10, 50, 100] } } # <- { "return": {} } # -# Example: -# -# Set new histogram only for write, other histograms will remain -# not changed (or not created): +# .. code-block:: QMP +# :caption: Example: Set new histogram only for write, other +# histograms will remain not changed (or not created): # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0", # "boundaries-write": [10, 50, 100] } } # <- { "return": {} } # -# Example: -# -# Set new histograms with the following intervals: +# .. code-block:: QMP +# :caption: Example: Set new histograms with the following intervals: # read, flush: [0, 10), [10, 50), [50, 100), [100, +inf) # write: [0, 1000), [1000, 5000), [5000, +inf) # @@ -575,9 +584,8 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: -# -# Remove all latency histograms: +# .. code-block:: QMP +# :caption: Example: Remove all latency histograms: # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } } diff --git a/qapi/char.json b/qapi/char.json index 0f39c2d5cdf..a119bbb70b5 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -40,7 +40,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-chardev" } # <- { @@ -86,7 +87,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-chardev-backends" } # <- { @@ -141,7 +143,8 @@ # # Since: 1.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "ringbuf-write", # "arguments": { "device": "foo", @@ -177,7 +180,8 @@ # # Since: 1.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "ringbuf-read", # "arguments": { "device": "foo", @@ -698,19 +702,26 @@ # # Since: 1.4 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # -> { "execute" : "chardev-add", # "arguments" : { "id" : "foo", # "backend" : { "type" : "null", "data" : {} } } } # <- { "return": {} } # +# .. code-block:: QMP +# :caption: Example +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "bar", # "backend" : { "type" : "file", # "data" : { "out" : "/tmp/bar.log"= } } } } # <- { "return": {} } # +# .. code-block:: QMP +# :caption: Example +# # -> { "execute" : "chardev-add", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } @@ -734,13 +745,17 @@ # # Since: 2.10 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # -> { "execute" : "chardev-change", # "arguments" : { "id" : "baz", # "backend" : { "type" : "pty", "data" : {} } } } # <- { "return": { "pty" : "/dev/pty/42" } } # +# .. code-block:: QMP +# :caption: Example +# # -> {"execute" : "chardev-change", # "arguments" : { # "id" : "charchannel2", @@ -771,7 +786,8 @@ # # Since: 1.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -788,7 +804,8 @@ # # Since: 2.10 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } } # <- { "return": {} } @@ -809,7 +826,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "VSERPORT_CHANGE", # "data": { "id": "channel0", "open": true }, diff --git a/qapi/control.json b/qapi/control.json index 2498e5dd6ba..938c94eb3ce 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -16,7 +16,8 @@ # the QMP greeting message. If the field is not provided, it # means no QMP capabilities will be enabled. (since 2.12) # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "qmp_capabilities", # "arguments": { "enable": [ "oob" ] } } @@ -97,7 +98,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-version" } # <- { @@ -134,7 +136,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-commands" } # <- { @@ -149,8 +152,8 @@ # ] # } # -# Note: This example has been shortened as the real response is too -# long. +# This example has been shortened as the real response is too long. +# ## { 'command': 'query-commands', 'returns': ['CommandInfo'], 'allow-preconfig': true } @@ -165,7 +168,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "quit" } # <- { "return": {} } diff --git a/qapi/dump.json b/qapi/dump.json index f9aee7ea1dd..758dc90755a 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -94,7 +94,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "dump-guest-memory", # "arguments": { "paging": false, "protocol": "fd:dump" } } @@ -150,7 +151,8 @@ # # Since: 2.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-dump" } # <- { "return": { "status": "active", "completed": 1024000, @@ -171,7 +173,8 @@ # # Since: 2.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "DUMP_COMPLETED", # "data": { "result": { "total": 1090650112, "status": "completed= ", @@ -202,7 +205,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-dump-guest-memory-capability" } # <- { "return": { "formats": diff --git a/qapi/machine-target.json b/qapi/machine-target.json index a8d9ec87f59..5d31408abfa 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -475,7 +475,8 @@ # # Since: 8.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "CPU_POLARIZATION_CHANGE", # "data": { "polarization": "horizontal" }, diff --git a/qapi/machine.json b/qapi/machine.json index e9c9bef940d..42f65ce1525 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -104,7 +104,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-cpus-fast" } # <- { "return": [ @@ -221,7 +222,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-machines", "arguments": { "compat-props": tru= e } } # <- { "return": [ @@ -320,7 +322,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-uuid" } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } } @@ -354,7 +357,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "system_reset" } # <- { "return": {} } @@ -373,7 +377,8 @@ # request or that it has shut down. Many guests will respond to this # command by prompting the user in some way. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "system_powerdown" } # <- { "return": {} } @@ -393,7 +398,8 @@ # .. note:: Prior to 4.0, this command does nothing in case the guest # isn't suspended. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "system_wakeup" } # <- { "return": {} } @@ -444,7 +450,8 @@ # .. note:: Prior to 2.1, this command was only supported for x86 and # s390 VMs # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "inject-nmi" } # <- { "return": {} } @@ -473,7 +480,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } } @@ -841,7 +849,8 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "memsave", # "arguments": { "val": 10, @@ -867,7 +876,8 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "pmemsave", # "arguments": { "val": 10, @@ -928,7 +938,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-memdev" } # <- { "return": [ @@ -1046,10 +1057,8 @@ # # Since: 2.7 # -# Examples: -# -# For pseries machine type started with -smp 2,cores=3D2,maxcpus=3D4 -# -cpu POWER8: +# .. code-block:: QMP +# :caption: Example: For pseries machine type started with ``-smp 2,cor= es=3D2,maxcpus=3D4 -cpu POWER8``: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1059,7 +1068,8 @@ # "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"} # ]} # -# For pc machine type started with -smp 1,maxcpus=3D2: +# .. code-block:: QMP +# :caption: Example: For pc machine type started with ``-smp 1,maxcpus= =3D2``: # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1074,8 +1084,8 @@ # } # ]} # -# For s390x-virtio-ccw machine type started with -smp 1,maxcpus=3D2 -# -cpu qemu (Since: 2.11): +# .. code-block:: QMP +# :caption: Example: For s390x-virtio-ccw machine type started with ``-= smp 1,maxcpus=3D2 -cpu qemu`` (Since: 2.11): # # -> { "execute": "query-hotpluggable-cpus" } # <- {"return": [ @@ -1129,12 +1139,14 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "balloon", "arguments": { "value": 536870912 } } # <- { "return": {} } # -# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# With a 2.5GiB guest this command inflated the ballon to 3GiB. +# ## { 'command': 'balloon', 'data': {'value': 'int'} } =20 @@ -1165,7 +1177,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-balloon" } # <- { "return": { @@ -1189,7 +1202,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "BALLOON_CHANGE", # "data": { "actual": 944766976 }, @@ -1230,7 +1244,8 @@ # # Since: 8.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-hv-balloon-status-report" } # <- { "return": { @@ -1251,7 +1266,8 @@ # # Since: 8.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "HV_BALLOON_STATUS_REPORT", # "data": { "committed": 816640000, "available": 3333054464 }, @@ -1283,7 +1299,8 @@ # Return the amount of initially allocated and present hotpluggable # (if enabled) memory in bytes. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-memory-size-summary" } # <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } } @@ -1562,7 +1579,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-memory-devices" } # <- { "return": [ { "data": @@ -1596,7 +1614,8 @@ # # Since: 5.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", # "data": { "id": "vm0", "size": 1073741824, @@ -1622,7 +1641,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "MEM_UNPLUG_ERROR", # "data": { "device": "dimm1", @@ -1882,7 +1902,8 @@ # # Since: 7.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "dumpdtb" } # "arguments": { "filename": "fdt.dtb" } } diff --git a/qapi/migration.json b/qapi/migration.json index a7b8ff138e3..a30d519d7c1 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -283,14 +283,14 @@ # # Since: 0.14 # -# Examples: -# -# 1. Before the first migration +# .. code-block:: QMP +# :caption: Example: Before the first migration # # -> { "execute": "query-migrate" } # <- { "return": {} } # -# 2. Migration is done and has succeeded +# .. code-block:: QMP +# :caption: Example: Migration is done and has succeeded # # -> { "execute": "query-migrate" } # <- { "return": { @@ -310,12 +310,14 @@ # } # } # -# 3. Migration is done and has failed +# .. code-block:: QMP +# :caption: Example: Migration is done and has failed # # -> { "execute": "query-migrate" } # <- { "return": { "status": "failed" } } # -# 4. Migration is being performed: +# .. code-block:: QMP +# :caption: Example: Migration is being performed # # -> { "execute": "query-migrate" } # <- { @@ -336,7 +338,35 @@ # } # } # -# 5. Migration is being performed and XBZRLE is active: +# .. code-block:: QMP +# :caption: Example: Migration is being performed and XBZRLE is active +# +# -> { "execute": "query-migrate" } +# <- { +# "return":{ +# "status":"active", +# "total-time":12345, +# "setup-time":12345, +# "expected-downtime":12345, +# "ram":{ +# "total":1057024, +# "remaining":1053304, +# "transferred":3720, +# "duplicate":123, +# "normal":123, +# "normal-bytes":123456, +# "dirty-sync-count":15 +# }, +# "disk":{ +# "total":20971520, +# "remaining":20880384, +# "transferred":91136 +# } +# } +# } +# +# .. code-block:: QMP +# :caption: Example: Migration is being performed and XBZRLE is active # # -> { "execute": "query-migrate" } # <- { @@ -510,7 +540,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-set-capabilities" , "arguments": # { "capabilities": [ { "capability": "xbzrle", "state": true } ]= } } @@ -528,7 +559,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-migrate-capabilities" } # <- { "return": [ @@ -1030,7 +1062,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-set-parameters" , # "arguments": { "multifd-channels": 5 } } @@ -1228,7 +1261,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-migrate-parameters" } # <- { "return": { @@ -1252,7 +1286,8 @@ # # Since: 2.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-start-postcopy" } # <- { "return": {} } @@ -1268,7 +1303,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001}, # "event": "MIGRATION", @@ -1287,7 +1323,8 @@ # # Since: 2.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225}, # "event": "MIGRATION_PASS", "data": {"pass": 2} } @@ -1371,7 +1408,8 @@ # # Since: 3.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172}, # "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "re= quest" } } @@ -1414,7 +1452,8 @@ # # Since: 2.8 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "x-colo-lost-heartbeat" } # <- { "return": {} } @@ -1433,7 +1472,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate_cancel" } # <- { "return": {} } @@ -1449,7 +1489,8 @@ # # Since: 2.11 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-continue" , "arguments": # { "state": "pre-switchover" } } @@ -1582,7 +1623,8 @@ # 6. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } } # <- { "return": {} } @@ -1661,7 +1703,8 @@ # 5. The 'uri' and 'channels' arguments are mutually exclusive; # exactly one of the two should be present. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-incoming", # "arguments": { "uri": "tcp:0:4446" } } @@ -1712,7 +1755,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-save-devices-state", # "arguments": { "filename": "/tmp/save" } } @@ -1730,7 +1774,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-set-global-dirty-log", # "arguments": { "enable": true } } @@ -1750,7 +1795,8 @@ # # Since: 2.7 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-load-devices-state", # "arguments": { "filename": "/tmp/resume" } } @@ -1770,7 +1816,8 @@ # @failover: true to do failover, false to stop. Cannot be specified # if 'enable' is true. Default value is false. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-set-replication", # "arguments": {"enable": true, "primary": false} } @@ -1805,7 +1852,8 @@ # # Returns: A @ReplicationStatus object showing the status. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-xen-replication-status" } # <- { "return": { "error": false } } @@ -1821,7 +1869,8 @@ # # Xen uses this command to notify replication to trigger a checkpoint. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-colo-do-checkpoint" } # <- { "return": {} } @@ -1859,7 +1908,8 @@ # # Returns: A @COLOStatus object showing the status. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-colo-status" } # <- { "return": { "mode": "primary", "last-mode": "none", "reason": "= request" } } @@ -1877,7 +1927,8 @@ # # @uri: the URI to be used for the recovery of migration stream. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-recover", # "arguments": { "uri": "tcp:192.168.1.200:12345" } } @@ -1894,7 +1945,8 @@ # # Pause a migration. Currently it only supports postcopy. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "migrate-pause" } # <- { "return": {} } @@ -1915,7 +1967,8 @@ # # Since: 4.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "UNPLUG_PRIMARY", # "data": { "device-id": "hostdev0" }, @@ -2075,13 +2128,15 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # "sample-pages": 512}= } # <- { "return": {} } # -# Measure dirty rate using dirty bitmap for 500 milliseconds: +# .. code-block:: QMP +# :caption: Example: Measure dirty rate using dirty bitmap for 500 mill= iseconds: # # -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500, # "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} } @@ -2103,15 +2158,15 @@ # # Since: 5.2 # -# Examples: -# -# 1. Measurement is in progress: +# .. code-block:: QMP +# :caption: Example: Measurement is in progress # # <- {"status": "measuring", "sample-pages": 512, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": = 10, # "calc-time-unit": "second"} # -# 2. Measurement has been completed: +# .. code-block:: QMP +# :caption: Example: Measurement has been completed # # <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108, # "mode": "page-sampling", "start-time": 1693900454, "calc-time": = 10, @@ -2154,7 +2209,8 @@ # # Since: 7.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> {"execute": "set-vcpu-dirty-limit"} # "arguments": { "dirty-rate": 200, @@ -2178,7 +2234,8 @@ # # Since: 7.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> {"execute": "cancel-vcpu-dirty-limit"}, # "arguments": { "cpu-index": 1 } } @@ -2195,7 +2252,8 @@ # # Since: 7.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> {"execute": "query-vcpu-dirty-limit"} # <- {"return": [ @@ -2259,7 +2317,8 @@ # # If @tag already exists, an error will be reported # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "snapshot-save", # "arguments": { @@ -2329,7 +2388,8 @@ # device nodes that can have changed since the original @snapshot-save # command execution. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "snapshot-load", # "arguments": { @@ -2390,7 +2450,8 @@ # to determine completion and to fetch details of any errors that # arise. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "snapshot-delete", # "arguments": { diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 4e0a6492a9a..ccbed866195 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -11,7 +11,8 @@ # # Since: 2.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "rtc-reset-reinjection" } # <- { "return": {} } @@ -89,7 +90,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-sev" } # <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0, @@ -120,7 +122,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-sev-launch-measure" } # <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } } @@ -165,7 +168,8 @@ # # Since: 2.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-sev-capabilities" } # <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE", @@ -219,7 +223,8 @@ # # Since: 6.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute" : "query-sev-attestation-report", # "arguments": { "mnonce": "aaaaaaa" } } @@ -239,7 +244,8 @@ # # Since: 2.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "dump-skeys", # "arguments": { "filename": "/tmp/skeys" } } @@ -284,7 +290,8 @@ # # Since: 2.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-gic-capabilities" } # <- { "return": [{ "version": 2, "emulated": true, "kernel": false }, @@ -342,7 +349,8 @@ # # Since: 6.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-sgx" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -361,7 +369,8 @@ # # Since: 6.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-sgx-capabilities" } # <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true, @@ -436,7 +445,8 @@ # # Since: 8.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-event-list" } # <- { "return": [ @@ -474,7 +484,8 @@ # # Since: 8.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "xen-event-inject", "arguments": { "port": 1 } } # <- { "return": { } } diff --git a/qapi/misc.json b/qapi/misc.json index b04efbadec6..39bf8e30df1 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -30,7 +30,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "add_client", "arguments": { "protocol": "vnc", # "fdname": "myclient" } } @@ -60,7 +61,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-name" } # <- { "return": { "name": "qemu-name" } } @@ -111,7 +113,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-iothreads" } # <- { "return": [ @@ -144,7 +147,8 @@ # In the "suspended" state, it will completely stop the VM and cause # a transition to the "paused" state. (Since 9.0) # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "stop" } # <- { "return": {} } @@ -168,7 +172,8 @@ # this command will transition back to the "suspended" state. (Since # 9.0) # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "cont" } # <- { "return": {} } @@ -192,7 +197,8 @@ # # Since: 3.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "x-exit-preconfig" } # <- { "return": {} } @@ -232,7 +238,8 @@ # # * Commands that prompt the user for data don't currently work. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "human-monitor-command", # "arguments": { "command-line": "info kvm" } } @@ -258,7 +265,8 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -285,7 +293,8 @@ # The 'closefd' command can be used to explicitly close the file # descriptor when it is no longer needed. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "get-win32-socket", # "arguments": { "info": "abcd123..", "fdname": "skclient" } } @@ -302,7 +311,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } # <- { "return": {} } @@ -345,7 +355,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } # <- { "return": { "fdset-id": 1, "fd": 3 } } @@ -374,7 +385,8 @@ # .. note:: If @fd is not specified, all file descriptors in @fdset-id # will be removed. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 }= } # <- { "return": {} } @@ -420,7 +432,8 @@ # # .. note:: The list of fd sets is shared by all monitor connections. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-fdsets" } # <- { "return": [ @@ -523,7 +536,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-command-line-options", # "arguments": { "option": "option-rom" } } @@ -565,7 +579,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "RTC_CHANGE", # "data": { "offset": 78 }, @@ -592,7 +607,8 @@ # # Since: 7.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "VFU_CLIENT_HANGUP", # "data": { "vfu-id": "vfu1", diff --git a/qapi/net.json b/qapi/net.json index 4ac7fdc7e6c..adef3e6633d 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -26,7 +26,8 @@ # command will succeed even if the network adapter does not support # link status notification. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "set_link", # "arguments": { "name": "e1000.0", "up": false } } @@ -46,7 +47,8 @@ # Errors: # - If @type is not a valid network backend, DeviceNotFound # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "netdev_add", # "arguments": { "type": "user", "id": "netdev1", @@ -68,7 +70,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } } # <- { "return": {} } @@ -835,7 +838,8 @@ # # Since: 1.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } } # <- { "return": [ @@ -880,7 +884,8 @@ # # Since: 1.6 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "NIC_RX_FILTER_CHANGED", # "data": { "name": "vnet0", @@ -927,7 +932,8 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "announce-self", # "arguments": { @@ -952,7 +958,8 @@ # # Since: 4.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "FAILOVER_NEGOTIATED", # "data": { "device-id": "net1" }, @@ -972,7 +979,8 @@ # # Since: 7.2 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", @@ -980,6 +988,9 @@ # "host": "::1", "type": "inet" } }, # "timestamp": { "seconds": 1666269863, "microseconds": 311222 } } # +# .. code-block:: QMP +# :caption: Example +# # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0", # "addr": { "path": "/tmp/qemu0", "type": "unix" } }, @@ -998,7 +1009,8 @@ # # Since: 7.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "NETDEV_STREAM_DISCONNECTED", # "data": {"netdev-id": "netdev0"}, diff --git a/qapi/pci.json b/qapi/pci.json index f51159a2c4c..9192212661b 100644 --- a/qapi/pci.json +++ b/qapi/pci.json @@ -182,7 +182,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-pci" } # <- { "return": [ @@ -311,8 +312,7 @@ # ] # } # -# Note: This example has been shortened as the real response is too -# long. +# This example has been shortened as the real response is too long. # ## { 'command': 'query-pci', 'returns': ['PciInfo'] } diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 5e33da7228f..66fbcbd3619 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -20,11 +20,7 @@ # understand. However, in real protocol usage, they're emitted as a # single line. # -# Also, the following notation is used to denote data flow: -# -# Example: -# -# :: +# Also, the following notation is used to denote data flow:: # # -> data issued by the Client # <- Server data response diff --git a/qapi/qdev.json b/qapi/qdev.json index d031fc3590d..cfe403fea20 100644 --- a/qapi/qdev.json +++ b/qapi/qdev.json @@ -62,7 +62,8 @@ # the ``-device DEVICE,help`` command-line argument, where DEVICE # is the device's name. # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "device_add", # "arguments": { "driver": "e1000", "id": "net1", @@ -104,12 +105,16 @@ # # Since: 0.14 # -# Examples: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "device_del", # "arguments": { "id": "net1" } } # <- { "return": {} } # +# .. code-block:: QMP +# :caption: Example +# # -> { "execute": "device_del", # "arguments": { "id": "/machine/peripheral-anon/device[0]" } } # <- { "return": {} } @@ -130,7 +135,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "DEVICE_DELETED", # "data": { "device": "virtio-net-pci-0", @@ -152,7 +158,8 @@ # # Since: 6.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "DEVICE_UNPLUG_GUEST_ERROR", # "data": { "device": "core1", diff --git a/qapi/qom.json b/qapi/qom.json index e927f4a3c5d..80357537b65 100644 --- a/qapi/qom.json +++ b/qapi/qom.json @@ -59,7 +59,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "qom-list", # "arguments": { "path": "/chardevs" } } @@ -104,16 +105,16 @@ # # Since: 1.2 # -# Examples: -# -# 1. Use absolute path +# .. code-block:: QMP +# :caption: Example: Use absolute path # # -> { "execute": "qom-get", # "arguments": { "path": "/machine/unattached/device[0]", # "property": "hotplugged" } } # <- { "return": false } # -# 2. Use partial path +# .. code-block:: QMP +# :caption: Example: Use partial path # # -> { "execute": "qom-get", # "arguments": { "path": "unattached/sysbus", @@ -139,7 +140,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "qom-set", # "arguments": { "path": "/machine", @@ -1080,7 +1082,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1", @@ -1102,7 +1105,8 @@ # # Since: 2.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} } diff --git a/qapi/replay.json b/qapi/replay.json index d3559f9c8f7..f0351b6d9c1 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -54,7 +54,8 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-replay" } # <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220= 414 } } @@ -76,7 +77,8 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "replay-break", "arguments": { "icount": 220414 } } # <- { "return": {} } @@ -91,7 +93,8 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "replay-delete-break" } # <- { "return": {} } @@ -112,7 +115,8 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "replay-seek", "arguments": { "icount": 220414 } } # <- { "return": {} } diff --git a/qapi/rocker.json b/qapi/rocker.json index 9f95e638309..da5cc2b9e01 100644 --- a/qapi/rocker.json +++ b/qapi/rocker.json @@ -30,7 +30,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-rocker", "arguments": { "name": "sw1" } } # <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}} @@ -98,7 +99,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" }= } # <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1", @@ -240,7 +242,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-rocker-of-dpa-flows", # "arguments": { "name": "sw1" } } @@ -315,7 +318,8 @@ # # Since: 2.4 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-rocker-of-dpa-groups", # "arguments": { "name": "sw1" } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 252d7d6afa7..6b0322de4d7 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -123,7 +123,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-status" } # <- { "return": { "running": true, @@ -152,7 +153,8 @@ # # Since: 0.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "SHUTDOWN", # "data": { "guest": true, "reason": "guest-shutdown" }, @@ -168,7 +170,8 @@ # # Since: 0.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "POWERDOWN", # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } @@ -189,7 +192,8 @@ # # Since: 0.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "RESET", # "data": { "guest": false, "reason": "guest-reset" }, @@ -204,7 +208,8 @@ # # Since: 0.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "STOP", # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } @@ -218,7 +223,8 @@ # # Since: 0.12 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "RESUME", # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } @@ -233,7 +239,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "SUSPEND", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -252,7 +259,8 @@ # # Since: 1.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "SUSPEND_DISK", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } @@ -267,7 +275,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "WAKEUP", # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } @@ -289,7 +298,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "WATCHDOG", # "data": { "action": "reset" }, @@ -382,7 +392,8 @@ # # Since: 2.11 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "watchdog-set-action", # "arguments": { "action": "inject-nmi" } } @@ -406,7 +417,8 @@ # # Since: 6.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "set-action", # "arguments": { "reboot": "shutdown", @@ -433,7 +445,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "GUEST_PANICKED", # "data": { "action": "pause" }, @@ -453,7 +466,8 @@ # # Since: 5.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" }, @@ -597,7 +611,8 @@ # # Since: 5.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor", diff --git a/qapi/tpm.json b/qapi/tpm.json index 1577b5c259d..07b7b5bd9fd 100644 --- a/qapi/tpm.json +++ b/qapi/tpm.json @@ -31,7 +31,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-tpm-models" } # <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] } @@ -62,7 +63,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-tpm-types" } # <- { "return": [ "passthrough", "emulator" ] } @@ -168,7 +170,8 @@ # # Since: 1.5 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-tpm" } # <- { "return": diff --git a/qapi/trace.json b/qapi/trace.json index 043d12f83e0..3af64027759 100644 --- a/qapi/trace.json +++ b/qapi/trace.json @@ -64,7 +64,8 @@ # # Since: 2.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "trace-event-get-state", # "arguments": { "name": "qemu_memalign" } } @@ -94,7 +95,8 @@ # # Since: 2.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "trace-event-set-state", # "arguments": { "name": "qemu_memalign", "enable": true } } diff --git a/qapi/transaction.json b/qapi/transaction.json index bcb05fdedd6..3f06ce9c1c6 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -244,7 +244,8 @@ # # Since: 1.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "transaction", # "arguments": { "actions": [ diff --git a/qapi/ui.json b/qapi/ui.json index ec72998e28e..856b3779d77 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -81,7 +81,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "set_password", "arguments": { "protocol": "vnc", # "password": "secret" = } } @@ -140,7 +141,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "expire_password", "arguments": { "protocol": "vnc", # "time": "+60" } } @@ -182,7 +184,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "screendump", # "arguments": { "filename": "/tmp/image" } } @@ -324,7 +327,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-spice" } # <- { "return": { @@ -373,7 +377,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_CONNECTED", @@ -399,7 +404,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_INITIALIZED", @@ -426,7 +432,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_DISCONNECTED", @@ -447,7 +454,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_MIGRATE_COMPLETED" } @@ -653,7 +661,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-vnc" } # <- { "return": { @@ -718,7 +727,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "VNC_CONNECTED", # "data": { @@ -745,7 +755,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "VNC_INITIALIZED", # "data": { @@ -771,7 +782,8 @@ # # Since: 0.13 # -# Example: +# .. code-block:: QMP +# :caption: Example # # <- { "event": "VNC_DISCONNECTED", # "data": { @@ -819,7 +831,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-mice" } # <- { "return": [ @@ -1028,7 +1041,8 @@ # # Since: 1.3 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "send-key", # "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" }, @@ -1264,9 +1278,8 @@ # property, so it is possible to map which console belongs to which # device and display. # -# Examples: -# -# 1. Press left mouse button. +# .. code-block:: QMP +# :caption: Example: Press left mouse button. # # -> { "execute": "input-send-event", # "arguments": { "device": "video0", @@ -1280,7 +1293,8 @@ # "data" : { "down": false, "button": "left" } } ] = } } # <- { "return": {} } # -# 2. Press ctrl-alt-del. +# .. code-block:: QMP +# :caption: Example: Press ctrl-alt-del. # # -> { "execute": "input-send-event", # "arguments": { "events": [ @@ -1292,7 +1306,8 @@ # "key": {"type": "qcode", "data": "delete" } } } ] } } # <- { "return": {} } # -# 3. Move mouse pointer to absolute coordinates (20000, 400). +# .. code-block:: QMP +# :caption: Example: Move mouse pointer to absolute coordinates (20000,= 400). # # -> { "execute": "input-send-event" , # "arguments": { "events": [ @@ -1605,7 +1620,8 @@ # # Since: 6.0 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "display-reload", # "arguments": { "type": "vnc", "tls-certs": true } } @@ -1658,7 +1674,8 @@ # # Since: 7.1 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "display-update", # "arguments": { "type": "vnc", "addresses": @@ -1689,7 +1706,8 @@ # # Since: 0.14 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "client_migrate_info", # "arguments": { "protocol": "spice", diff --git a/qapi/virtio.json b/qapi/virtio.json index b91f3cdd0df..adf5def9dd6 100644 --- a/qapi/virtio.json +++ b/qapi/virtio.json @@ -34,7 +34,8 @@ # # Since: 7.2 # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "x-query-virtio" } # <- { "return": [ @@ -203,9 +204,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Poll for the status of virtio-crypto (no vhost-crypto active) +# .. code-block:: QMP +# :caption: Example: Poll for the status of virtio-crypto (no vhost-cry= pto active) # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-back= end" } @@ -261,7 +261,8 @@ # } # } # -# 2. Poll for the status of virtio-net (vhost-net is active) +# .. code-block:: QMP +# :caption: Example: Poll for the status of virtio-net (vhost-net is ac= tive) # # -> { "execute": "x-query-virtio-status", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virt= io-backend" } @@ -568,9 +569,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running) +# .. code-block:: QMP +# :caption: Example: Get VirtQueueStatus for virtio-vsock (vhost-vsock = running) # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backe= nd", @@ -593,7 +593,8 @@ # } # } # -# 2. Get VirtQueueStatus for virtio-serial (no vhost) +# .. code-block:: QMP +# :caption: Example: Get VirtQueueStatus for virtio-serial (no vhost) # # -> { "execute": "x-query-virtio-queue-status", # "arguments": { "path": "/machine/peripheral-anon/device[0]/virt= io-backend", @@ -690,9 +691,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Get vhost_virtqueue status for vhost-crypto +# .. code-block:: QMP +# :caption: Example: Get vhost_virtqueue status for vhost-crypto # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-back= end", @@ -715,7 +715,8 @@ # } # } # -# 2. Get vhost_virtqueue status for vhost-vsock +# .. code-block:: QMP +# :caption: Example: Get vhost_virtqueue status for vhost-vsock # # -> { "execute": "x-query-virtio-vhost-queue-status", # "arguments": { "path": "/machine/peripheral/vsock0/virtio-backe= nd", @@ -839,9 +840,8 @@ # # Since: 7.2 # -# Examples: -# -# 1. Introspect on virtio-net's VirtQueue 0 at index 5 +# .. code-block:: QMP +# :caption: Example: Introspect on virtio-net's VirtQueue 0 at index 5 # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[1]/virt= io-backend", @@ -870,7 +870,8 @@ # } # } # -# 2. Introspect on virtio-crypto's VirtQueue 1 at head +# .. code-block:: QMP +# :caption: Example: Introspect on virtio-crypto's VirtQueue 1 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral/crypto0/virtio-back= end", @@ -898,7 +899,8 @@ # } # } # -# 3. Introspect on virtio-scsi's VirtQueue 2 at head +# .. code-block:: QMP +# :caption: Example: Introspect on virtio-scsi's VirtQueue 2 at head # # -> { "execute": "x-query-virtio-queue-element", # "arguments": { "path": "/machine/peripheral-anon/device[2]/virt= io-backend", diff --git a/qapi/yank.json b/qapi/yank.json index 89f2f4d199b..a64b77e846c 100644 --- a/qapi/yank.json +++ b/qapi/yank.json @@ -81,7 +81,8 @@ # Errors: # - If any of the YankInstances doesn't exist, DeviceNotFound # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "yank", # "arguments": { @@ -104,7 +105,8 @@ # # Returns: list of @YankInstance # -# Example: +# .. code-block:: QMP +# :caption: Example # # -> { "execute": "query-yank" } # <- { "return": [ diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 8b1da96124e..afc0b444034 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -554,9 +554,12 @@ def get_doc(self) -> 'QAPIDoc': no_more_args =3D True intro =3D False elif match :=3D re.match( - r'(Returns|Errors|Since|Notes?|Examples?|TODO): *', + r'(Returns|Errors|Since|Notes?|Examples?(?!::)|TOD= O)' + r': *', line): - # tagged section + # tagged section. + # Examples sections followed by two colons are exclude= d; + # those are raw rST syntax! =20 if 'Note' in match.group(1): emsg =3D ( @@ -566,6 +569,14 @@ def get_doc(self) -> 'QAPIDoc': ) raise QAPIParseError(self, emsg) =20 + if match.group(1).startswith("Example"): + emsg =3D ( + f"The '{match.group(1)}' section is deprecated= . " + "Please use rST's '.. code-block:: QMP' direct= ive," + " 'Example::', or other suitable markup instea= d." + ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text =3D line[match.end():] if text: diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.j= son index 0a294eb324e..57e2e591938 100644 --- a/tests/qapi-schema/doc-good.json +++ b/tests/qapi-schema/doc-good.json @@ -46,11 +46,12 @@ # # Duis aute irure dolor # -# Example: +# .. code-block:: QMP # # -> in # <- out -# Examples: +# .. code-block:: +# # - *verbatim* # - {braces} ## @@ -170,12 +171,13 @@ # # Duis aute irure dolor # -# Example: +# .. code-block:: # # -> in # <- out # -# Examples: +# .. code-block:: +# # - *verbatim* # - {braces} # @@ -194,7 +196,7 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. code-block:: # # -> in # diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index 2c9b4e419cb..cd967c8b2e0 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -93,11 +93,12 @@ Notes: =20 Duis aute irure dolor =20 -Example: +.. code-block:: QMP =20 -> in <- out -Examples: +.. code-block:: + - *verbatim* - {braces} doc symbol=3DEnum @@ -184,10 +185,14 @@ frobnicate - Ut enim ad minim veniam =20 Duis aute irure dolor - section=3DExample + +.. code-block:: + -> in <- out - section=3DExamples + +.. code-block:: + - *verbatim* - {braces} section=3DSince @@ -199,7 +204,9 @@ If you're bored enough to read this, go see a video of = boxed cats a feature feature=3Dcmd-feat2 another feature - section=3DExample + section=3DNone +.. code-block:: + -> in =20 <- out diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index b89f35d5476..808ca7f73a1 100644 --- a/tests/qapi-schema/doc-good.txt +++ b/tests/qapi-schema/doc-good.txt @@ -33,9 +33,10 @@ Returns: the King Since: the first age Notes: =20 Duis aute irure dolor =20 -Example: +-> in <- out .. code-block: =20 --> in <- out Examples: - *verbatim* - {braces} + - *verbatim* + - {braces} =20 =20 "Enum" (Enum) @@ -219,17 +220,9 @@ Notes: =20 Duis aute irure dolor =20 - -Example -~~~~~~~ - -> in <- out =20 - -Examples -~~~~~~~~ - - *verbatim* - {braces} =20 @@ -260,10 +253,6 @@ Features "cmd-feat2" another feature =20 - -Example -~~~~~~~ - -> in =20 <- out --=20 2.44.0