From nobody Thu Apr 3 09:59:32 2025 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=1740368364; cv=none; d=zohomail.com; s=zohoarc; b=NotTUK3bztag842A9ROU89Sp6O6KluI6/P4tw+IaA12E8/Llkd3Kn1k0dn8PRR5PPYVRicABQjeSlAZuzw9w7BLlh0QArWXs5Lfo+1mi7ehAEPicEvE+G7hYZWF/+yK9DGrp8kpooG9B+0MrwsCfWgMCR0vji3s6/JLifopAU4M= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368364; 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=dcjzzdXuubckXiBP8XE/buE8yp7h0bKbvstfTkBPOlg=; b=Z18/zE+PrUGTNcweEsKYpgx40dj1PkAanhokSI1mQ5qB7jsr93p8lEAXZSobJSDkl5E75qZcWzIdWScZyizAYuY9S4BmAe+jguena49wgGo7/71nxIWN8YZim0ASRPb8eBQtDvkm4mg856eXn59ZSwuYxWCKABU0vVIubPtz95w= 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 1740368364285512.4609500657754; Sun, 23 Feb 2025 19:39:24 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIA-0001O5-CQ; Sun, 23 Feb 2025 22:38:02 -0500 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 1tmPI5-0001Mm-Pr for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:37:57 -0500 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 1tmPI2-0005QI-NF for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:37:57 -0500 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-103-gNOQyw2cO96Q8CH-6gmnig-1; Sun, 23 Feb 2025 22:37:49 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 84B8F19373D8; Mon, 24 Feb 2025 03:37:47 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 978FD19560A3; Mon, 24 Feb 2025 03:37:44 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368271; 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=dcjzzdXuubckXiBP8XE/buE8yp7h0bKbvstfTkBPOlg=; b=iiXT2iVfTc2nbSr/fBY4jQQI8+FDdwvWm6RS7lt+esbKTAvkD+VFPhqMt9+5Nob1bjecKX IYYX69+SCto9HWNiEGNwSWVnw56NZsM4Jg7y5cWoVx2D2L1QLYR6YfhepwxqhhlYRGSYEV jfVvfj4qTZ7iQMxb7bTpSoqdI5kfbV8= X-MC-Unique: gNOQyw2cO96Q8CH-6gmnig-1 X-Mimecast-MFC-AGG-ID: gNOQyw2cO96Q8CH-6gmnig_1740368267 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 01/10] qapi: update pylintrc config Date: Sun, 23 Feb 2025 22:37:32 -0500 Message-ID: <20250224033741.222749-2-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368364677019000 Content-Type: text/plain; charset="utf-8" If you've got a newer pylint, it'll whine about positional arguments separately from the regular ones. Update the configuration to ignore both categories of warning. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- scripts/qapi/pylintrc | 1 + 1 file changed, 1 insertion(+) diff --git a/scripts/qapi/pylintrc b/scripts/qapi/pylintrc index c028a1f9f51..d24eece7411 100644 --- a/scripts/qapi/pylintrc +++ b/scripts/qapi/pylintrc @@ -17,6 +17,7 @@ disable=3Dconsider-using-f-string, too-many-arguments, too-many-branches, too-many-instance-attributes, + too-many-positional-arguments, too-many-statements, useless-option-value, =20 --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368363; cv=none; d=zohomail.com; s=zohoarc; b=Zmidv04qLlSgI/Lw/Gj7NDVfrA+gxZXRguRz3j1O3+8J+one0GqknXGix71O5lgATAZQvSN0kkX3LcKP9lfivX0F/3LM/2Y3jXpQaFPXwqYj1sSSXkFUPxw3AZCvXEhq7sCi8/sLT6ocBb35G/4qj6PA6OaXwNlLGELIepG5hJ4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368363; 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=uMKnABVrs8WDUSLAe63r5ZpgVJ7qK/QCZKTVO7yUAO8=; b=bmLgnTvMES9x0OebkpzRjhamHkdOMzsBRD6BwmDX7BXU8TDVguc4sSrG1T8ZLAmVNnQHOC8rXP7ziGzaFL4T4yYNH/AhReEnt1tsPxqI61daewNYHWJnwAx/XsSlsCmlgSpSEn89+Iyj+XSoRLLa7nQ4oe4Mt+H0oUfJOCvRyqY= 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 1740368363746668.083875196177; Sun, 23 Feb 2025 19:39:23 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPI6-0001Ml-1D; Sun, 23 Feb 2025 22:37:58 -0500 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 1tmPI4-0001MR-Cn for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:37:56 -0500 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 1tmPI2-0005QQ-38 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:37:56 -0500 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-693-i2dTjIZrP7GwchZHL3h93g-1; Sun, 23 Feb 2025 22:37:51 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DB8F2190FF83; Mon, 24 Feb 2025 03:37:49 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E0FE919560A3; Mon, 24 Feb 2025 03:37:47 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368272; 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=uMKnABVrs8WDUSLAe63r5ZpgVJ7qK/QCZKTVO7yUAO8=; b=XcTAj8Z/7il34UXkl1G5oHScpwaYPMzFN7VM3bWjlAkHkIYuvtb1MA6H6LbJuukgx0w56+ AIQdjo9rLYzKRZkxENj5ZXU3YiflL/JMTGWbau+FMomjDrvRXwr+O9Ed2jf47FZIUM11is Aii2kzMnxg9dnTRC478RBYl6jmDopmU= X-MC-Unique: i2dTjIZrP7GwchZHL3h93g-1 X-Mimecast-MFC-AGG-ID: i2dTjIZrP7GwchZHL3h93g_1740368270 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 02/10] python: add qapi static analysis tests Date: Sun, 23 Feb 2025 22:37:33 -0500 Message-ID: <20250224033741.222749-3-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368364536019000 Content-Type: text/plain; charset="utf-8" Update the python tests to also check qapi. No idea why I didn't do this before. I guess I was counting on moving it under python/ and then just forgot after that was NACKed. Oops, this turns out to be really easy. flake8, isort and mypy use the tool configuration from the existing python directory. pylint continues to use the special configuration located in scripts/qapi/ - that configuration is more permissive. If we wish to unify the two configurations, that's a separate series and a discussion for a later date. As a result of this patch, one would be able to run any of the following tests locally from the qemu.git/python directory and have it cover the scripts/qapi/ module as well. All of the following options run the python tests, static analysis tests, and linter checks; but with different combinations of dependencies and interpreters. - "make check-minreqs" Run tests specifically under our oldest supported Python and our oldest supported dependencies. This is the test that runs on GitLab as "check-python-minreqs". This helps ensure we do not regress support on older platforms accidentally. - "make check-tox" Runs the tests under the newest supported dependencies, but under each supported version of Python in turn. At time of writing, this is Python 3.8 to 3.13 inclusive. This test helps catch bleeding-edge problems before they become problems for developer workstations. This is the GitLab test "check-python-tox" and is an optionally run, may-fail test due to the unpredictable nature of new dependencies being released into the ecosystem that may cause regressions. - "make check-dev" Runs the tests under the newest supported dependencies using whatever version of Python the user happens to have installed. This is a quick convenience check that does not map to any particular GitLab test. (Note! check-dev may be busted on Fedora 41 and bleeding edge versions of setuptools. That's unrelated to this patch and I'll address it separately and soon. Thank you for your patience, --mgmt) Signed-off-by: John Snow Acked-by: Markus Armbruster --- python/tests/qapi-flake8.sh | 2 ++ python/tests/qapi-isort.sh | 2 ++ python/tests/qapi-mypy.sh | 2 ++ python/tests/qapi-pylint.sh | 4 ++++ 4 files changed, 10 insertions(+) create mode 100755 python/tests/qapi-flake8.sh create mode 100755 python/tests/qapi-isort.sh create mode 100755 python/tests/qapi-mypy.sh create mode 100755 python/tests/qapi-pylint.sh diff --git a/python/tests/qapi-flake8.sh b/python/tests/qapi-flake8.sh new file mode 100755 index 00000000000..51916a9019d --- /dev/null +++ b/python/tests/qapi-flake8.sh @@ -0,0 +1,2 @@ +#!/bin/sh -e +python3 -m flake8 ../scripts/qapi/ diff --git a/python/tests/qapi-isort.sh b/python/tests/qapi-isort.sh new file mode 100755 index 00000000000..60ed5eeb34d --- /dev/null +++ b/python/tests/qapi-isort.sh @@ -0,0 +1,2 @@ +#!/bin/sh -e +python3 -m isort --sp . -c ../scripts/qapi/ diff --git a/python/tests/qapi-mypy.sh b/python/tests/qapi-mypy.sh new file mode 100755 index 00000000000..377b29b873b --- /dev/null +++ b/python/tests/qapi-mypy.sh @@ -0,0 +1,2 @@ +#!/bin/sh -e +python3 -m mypy ../scripts/qapi diff --git a/python/tests/qapi-pylint.sh b/python/tests/qapi-pylint.sh new file mode 100755 index 00000000000..d4869578e54 --- /dev/null +++ b/python/tests/qapi-pylint.sh @@ -0,0 +1,4 @@ +#!/bin/sh -e +SETUPTOOLS_USE_DISTUTILS=3Dstdlib python3 -m pylint \ + --rcfile=3D../scripts/qapi/pylintrc \ + ../scripts/qapi/ --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368329; cv=none; d=zohomail.com; s=zohoarc; b=V1uDJTyrW0jzSwWxsCcbBcENSBS3LX0ePAL2uQjMjsjXtZqYSSTMAIgXxw/T3vpfxHHBnzE/fLZk2Md5ybKqjvj2/UvWBAbEMXZp7WfkXqymdUgJlx79gnxUqtECrBSrCCBOQVIu2Zz9cnVm9ifo2xBwVoG3+/UGPjmf02gMHU4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368329; 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=bTItdUrDg7Cd84ey97EQdcR9LPBq5Jivo28daai7VVk=; b=MPB2NtYrgbByqPjmcXuENBffvAZmvP21ujT3vLVKd1X85kMoSAgFaZJFVBBfTuQm8numm3+dGwSb2knt9N62v9O1LhHVf03+m5xQUe4f0GZtWTJUmfHf3NBA8lbeLxHfC0MdqLMK5eEKIAfNBp8AyCHPBce1zO44BgkvhdrhmzY= 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 1740368329345596.9842134061579; Sun, 23 Feb 2025 19:38:49 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIG-0001Op-KN; Sun, 23 Feb 2025 22:38:08 -0500 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 1tmPIA-0001Nt-S2 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:04 -0500 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 1tmPI8-0005Qu-8A for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:01 -0500 Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-141-k71PZCNSNfOgJi9BcGR15Q-1; Sun, 23 Feb 2025 22:37:54 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 43244196E078; Mon, 24 Feb 2025 03:37:53 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 0E8671956048; Mon, 24 Feb 2025 03:37:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368279; 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=bTItdUrDg7Cd84ey97EQdcR9LPBq5Jivo28daai7VVk=; b=Wh7qdzcHj7WCr+m4YrYETK2CtKt0ezVCb7N6Zsu8ywt7UHZ5HpbhYhohpkSvHV8N/IC+J5 iZnAbHsK8mV0ZhKxDBicaKe4UMQakXAkCK0mlf4KAUoyu4XBZqzpC9o40hKUtW6zyZJxRs XtheNh2+dB1RjpISf5CpgV2MJHDEbiw= X-MC-Unique: k71PZCNSNfOgJi9BcGR15Q-1 X-Mimecast-MFC-AGG-ID: k71PZCNSNfOgJi9BcGR15Q_1740368273 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 03/10] qapi: delete un-needed python static analysis configs Date: Sun, 23 Feb 2025 22:37:34 -0500 Message-ID: <20250224033741.222749-4-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368331432019100 Content-Type: text/plain; charset="utf-8" The pylint config is being left in place because the settings differ enough from the python/ directory settings that we need a chit-chat on how to merge them O:-) Everything else can go. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- scripts/qapi/.flake8 | 3 --- scripts/qapi/.isort.cfg | 7 ------- scripts/qapi/mypy.ini | 4 ---- 3 files changed, 14 deletions(-) delete mode 100644 scripts/qapi/.flake8 delete mode 100644 scripts/qapi/.isort.cfg delete mode 100644 scripts/qapi/mypy.ini diff --git a/scripts/qapi/.flake8 b/scripts/qapi/.flake8 deleted file mode 100644 index a873ff67309..00000000000 --- a/scripts/qapi/.flake8 +++ /dev/null @@ -1,3 +0,0 @@ -[flake8] -# Prefer pylint's bare-except checks to flake8's -extend-ignore =3D E722 diff --git a/scripts/qapi/.isort.cfg b/scripts/qapi/.isort.cfg deleted file mode 100644 index 643caa1fbd6..00000000000 --- a/scripts/qapi/.isort.cfg +++ /dev/null @@ -1,7 +0,0 @@ -[settings] -force_grid_wrap=3D4 -force_sort_within_sections=3DTrue -include_trailing_comma=3DTrue -line_length=3D72 -lines_after_imports=3D2 -multi_line_output=3D3 diff --git a/scripts/qapi/mypy.ini b/scripts/qapi/mypy.ini deleted file mode 100644 index 8109470a031..00000000000 --- a/scripts/qapi/mypy.ini +++ /dev/null @@ -1,4 +0,0 @@ -[mypy] -strict =3D True -disallow_untyped_calls =3D False -python_version =3D 3.8 --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368323; cv=none; d=zohomail.com; s=zohoarc; b=N+hFrnNT2HJPHcHP+Y6uqteXUR/whgNBmLVlPlM+B4J2vunPLDZOONHCPQjQKCddYL+srmm7jzpYlozt3qhRlakxaankDM41andhfS51cL9IYPl1SeMZCjNIF0Oo3gS7GqXALH0ICnu7haO6LNSFVXe+cOHKApydipy4VFVI4PQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368323; 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=vCf2xUI79U0RccCQtLTmvtWHcS6bUxwvEuD4GXikfUU=; b=bzMTrQZQIWAhF1LhlJdOzYHyMAhQZDKpvo9XRamJBHtVNSJBkYGg+At8fuSEkMC48YuX9wzax7RYX6l1ZuCwlqd32aqghV3BHJ81owUpOwmtw8YI5zGC7y7fmDMOuoeUKoTC6GYiZ8ubXkNOX0VZp22cL1bGtIjBH/tue5w5hek= 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 1740368323089816.1814022016458; Sun, 23 Feb 2025 19:38:43 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIN-0001Po-Ft; Sun, 23 Feb 2025 22:38:19 -0500 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 1tmPID-0001OM-0m for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:06 -0500 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 1tmPIA-0005RA-GO for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:04 -0500 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-493-z6PjGYb_Oma5TrXlFgQXfg-1; Sun, 23 Feb 2025 22:37:56 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 5FE5B1800872; Mon, 24 Feb 2025 03:37:55 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 845C219560A3; Mon, 24 Feb 2025 03:37:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368281; 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=vCf2xUI79U0RccCQtLTmvtWHcS6bUxwvEuD4GXikfUU=; b=GRoyl0I0y0S9VvesNCMjVaC1c2iiiHcQArMxmGcEjRi5w6Ko4gZHeQxBxDnsDdaapF4Tcn cYTjjfZxZNVun7t6e3euxLbHvtWQ+EPBudk0PHKyzf8Y+oq+gNez9AYoDezr6nHpY7WV0v h1OUnMirNp/PMUbnyLxb2ixPXpqib0o= X-MC-Unique: z6PjGYb_Oma5TrXlFgQXfg-1 X-Mimecast-MFC-AGG-ID: z6PjGYb_Oma5TrXlFgQXfg_1740368275 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 04/10] docs/qapidoc: support header-less freeform sections Date: Sun, 23 Feb 2025 22:37:35 -0500 Message-ID: <20250224033741.222749-5-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368324428019000 Content-Type: text/plain; charset="utf-8" The code as written crashes when a free-form documentation block doesn't start with a heading or subheading, for example: | ## | # Just text, no heading. | ## The code will attempt to use the `node` variable uninitialized. To fix, create a generic block to insert the doc text into. (This patch also removes a lingering pylint warning in the QAPIDoc implementation that prevents getting a clean baseline to use for forthcoming additions.) Fixes: 43e0d14ee09a (docs/sphinx: fix extra stuff in TOC after freeform QMP= sections) Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5f96b46270b..5a4d7388b29 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -421,6 +421,8 @@ def freeform(self, doc): node =3D self._start_new_heading(heading, len(leader)) if text =3D=3D '': return + else: + node =3D nodes.container() =20 self._parse_text_into_node(text, node) self._cur_doc =3D None --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368299; cv=none; d=zohomail.com; s=zohoarc; b=eBhdBoUz4jSZeVCpA5ynrb8ZYaHoJzUymscEncWj3dG5vYZy8N5gnu6V/1L7qPIcn34xVX9xP62tpkCTdhMnyW5hrnl/tIqvkK3Il0Mzo5L0S0M0o5vI3biSql2W3pcpGVreeFFwODhUL+SIuap7Tiu/K/RLr/CmLkEzD1go4vs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368299; 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=GyiRxmydcU0/fOZaO5aRgfQNpoUwmviAK70kDpUDoAk=; b=YHAqZwuI/6dEvQzita1tFib3Lpnjac+FV5mhjqyeDYijSnPIx7ihQacoNdd7OREYjwGXYgz3iX8+5UZcC7kuQUB4Rrc69zUuV4tQrJ5j3NLaa6DrPQtFJSRwIok11XaazZb4QKaGbhP/zODlSCapIowuQ/EzxIQxUOR+SXDDXaA= 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 1740368299465393.92402907165854; Sun, 23 Feb 2025 19:38:19 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIJ-0001PW-7i; Sun, 23 Feb 2025 22:38:13 -0500 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 1tmPID-0001ON-1Z for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:06 -0500 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 1tmPIB-0005RF-I2 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:04 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-539-gJy1PLhaOy66Ws0jH0HOPQ-1; Sun, 23 Feb 2025 22:37:58 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 728B218004A7; Mon, 24 Feb 2025 03:37:57 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id A164B19560A3; Mon, 24 Feb 2025 03:37:55 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368282; 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=GyiRxmydcU0/fOZaO5aRgfQNpoUwmviAK70kDpUDoAk=; b=TFr6BePDGhlSlUWYZRh4h55O755vxrTxH6JA7N5Fdm7nZO1hcSwJv2wtZ6Wt9qJjk8Nkvo miNNHpAwHwTN2dRVNqwjR9KER6YQf2Hymk9n3pW7xbt0BmqCFmTIJYwFdeDPXr8B8L+uFr yNKAHnqf+LB02SqcEdYGjVn80WcGs00= X-MC-Unique: gJy1PLhaOy66Ws0jH0HOPQ-1 X-Mimecast-MFC-AGG-ID: gJy1PLhaOy66Ws0jH0HOPQ_1740368277 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 05/10] qapi/parser: adjust info location for doc body section Date: Sun, 23 Feb 2025 22:37:36 -0500 Message-ID: <20250224033741.222749-6-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368300556019000 Content-Type: text/plain; charset="utf-8" Instead of using the info object for the doc block as a whole (which always points to the very first line of the block), 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. For example, this patch will move the info pointer for the "Hello!" untagged section ... > ## <-- from here ... > # Hello! <-- ... to here. > ## Signed-off-by: John Snow --- scripts/qapi/parser.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index adc85b5b394..36cb64a677a 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -687,7 +687,11 @@ def end(self) -> None: 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] + if not section.text: + # Section is empty so far; update info to start *here*. + section.info =3D info + section.text +=3D '\n' return # start new section section =3D self.Section(info) --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368396; cv=none; d=zohomail.com; s=zohoarc; b=GMOqUNNdcvmn+pfQQwH213lEtOfwVaiIWHjUs4ZcmFaZQvQCWshofy9E2Cwoq83M5HC5W36No7VxUxmMO/VGwlvMYiRpanWa+WhUDzJACUoCZYDCr28WjkmrvVFMCtH/HYOduUoh2xdW4gMJvJ9G8jUzp+ZoEktrdKNe+Ue4ueo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368396; 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=idbJdwJ8CDyE+xVdzPTbisC279pESEqsJVDljvElmiw=; b=KL12trFQTd8BEnLhcRitNTL+c5kKjNgsRL9rJEBg1bVtU+zdX/VB9hl3Jv6aK6DAsWKTTB+HOXnGlK08PQ8kEtL5Z07z6Tw+NL8LGMu62A/h/d0VmsSj+fRpE7MnHtm/jc1d6ZEjbrpIznPvwyyfWXCas3Jq/N5nwi1FwPlD2qo= 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 1740368396729228.568973548945; Sun, 23 Feb 2025 19:39:56 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPJ1-0001xz-Kq; Sun, 23 Feb 2025 22:38:55 -0500 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 1tmPIJ-0001Pn-D0 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:13 -0500 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 1tmPIE-0005RW-JK for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:09 -0500 Received: from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-150-vBHjB2TGPtCxt-ymG2hfiA-1; Sun, 23 Feb 2025 22:38:00 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8416319560B5; Mon, 24 Feb 2025 03:37:59 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id B45FA19560A3; Mon, 24 Feb 2025 03:37:57 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368285; 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=idbJdwJ8CDyE+xVdzPTbisC279pESEqsJVDljvElmiw=; b=dDAAtz/bCzetZWkf+b1oCPByR0hKqPOhb6Hr/ATBnhbeOfmWzoX3Khy1yV9psJ6fXHDfkT PTQD3/f3rUgckW1B6tiv0yQrsOhQfk20WLLPrZ4MTfoIJJwwnZxHs/nJD1bFuC95wFp9RD RxV9XssB5VHODCwRaq9pCDVleA0oXW0= X-MC-Unique: vBHjB2TGPtCxt-ymG2hfiA-1 X-Mimecast-MFC-AGG-ID: vBHjB2TGPtCxt-ymG2hfiA_1740368279 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 06/10] docs/qapidoc: remove example section support Date: Sun, 23 Feb 2025 22:37:37 -0500 Message-ID: <20250224033741.222749-7-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, 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_H2=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368398556019000 Content-Type: text/plain; charset="utf-8" Since commit 3c5f6114 (qapi: remove "Example" doc section), Example sections no longer exist, so this support in qapidoc is now dead code. Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 5a4d7388b29..61997fd21af 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -254,10 +254,6 @@ def _nodes_for_features(self, doc): section +=3D dlnode return [section] =20 - def _nodes_for_example(self, exampletext): - """Return list of doctree nodes for a code example snippet""" - return [nodes.literal_block(exampletext, exampletext)] - def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist =3D [] @@ -275,10 +271,7 @@ def _nodes_for_sections(self, doc): continue =20 snode =3D self._make_section(section.tag) - if section.tag.startswith('Example'): - snode +=3D self._nodes_for_example(dedent(section.text)) - else: - self._parse_text_into_node(dedent(section.text), snode) + self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist =20 --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368396; cv=none; d=zohomail.com; s=zohoarc; b=HvPJ1f4gpCuPt/ya462vOgx3FlIxTQaEroATDBJYac5yY8QwyZJsLoeFlIIUSa85VlvK2Uz4qxH5EUwa+CoU/IDH/NgMFJnRjUwmXLjPlk80Tp3DRZTTV7eIzfiv7JJVp4nJmHxjU1zzlx21jC54+nx4LHcEp7k4f9Lk+31vJac= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368396; 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=zMLbHhizeluJkqGGXl5VHpMeg84p0Ut5PhJj+s5R06k=; b=KXcESaQUeYx2jQHM0inU5xs9czT/tvFkIT0wtroZ5qVD9HM2dCB6jBW3VZl0fIltaRS0W4nHhKsQbOjXKyA7a44sgL3fGvHMoFZtvI7/vFpi3ojkGGemEZRCQgTnREHHhnBBhwz1zmDwWlK6iLxksfHUvFnd9c4h81ks9rjshpM= 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 1740368396732107.7121538787884; Sun, 23 Feb 2025 19:39:56 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIx-0001wB-He; Sun, 23 Feb 2025 22:38:51 -0500 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 1tmPIJ-0001Pm-C5 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:13 -0500 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 1tmPIF-0005Rb-TK for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:09 -0500 Received: from mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-610-CkQb5kcPMEyHKr9havTcwA-1; Sun, 23 Feb 2025 22:38:03 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 95F0019357B1; Mon, 24 Feb 2025 03:38:01 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id C810519560A3; Mon, 24 Feb 2025 03:37:59 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368286; 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=zMLbHhizeluJkqGGXl5VHpMeg84p0Ut5PhJj+s5R06k=; b=fOIJC/s73M0ECm2r0d7LjBYm1nXfUhGRyLClEfmP6Z75/IfgxaRHchKkg/0YWQhKUPgWja 0V3WJG3dYmGSY4lqLLk6toDrDAbw2nErCzKtU0CWAGRGoBDbWJWZeVFBC0sHpNdYevO7IL Lil3PVwfx9BSlER5Ug/QGY76rAk8CWM= X-MC-Unique: CkQb5kcPMEyHKr9havTcwA-1 X-Mimecast-MFC-AGG-ID: CkQb5kcPMEyHKr9havTcwA_1740368281 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 07/10] qapi: expand tags to all doc sections Date: Sun, 23 Feb 2025 22:37:38 -0500 Message-ID: <20250224033741.222749-8-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, 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_H2=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368399799019100 Content-Type: text/plain; charset="utf-8" This patch adds an explicit section "kind" to all QAPIDoc sections. Members/Features are now explicitly marked as such, with the name now being stored in a dedicated "name" field (which qapidoc.py was not actually using anyway.) The qapi-schema tests are updated to account for the new section names; mostly "TODO" becomes "Todo" and `None` becomes "Plain". Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 7 ++- scripts/qapi/parser.py | 109 ++++++++++++++++++++++++--------- tests/qapi-schema/doc-good.out | 10 +-- tests/qapi-schema/test-qapi.py | 2 +- 4 files changed, 90 insertions(+), 38 deletions(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 61997fd21af..d622398f1da 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -35,6 +35,7 @@ from docutils.statemachine import ViewList from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor +from qapi.parser import QAPIDoc from qapi.schema import QAPISchema =20 from sphinx import addnodes @@ -258,11 +259,11 @@ def _nodes_for_sections(self, doc): """Return list of doctree nodes for additional sections""" nodelist =3D [] for section in doc.sections: - if section.tag and section.tag =3D=3D 'TODO': + if section.kind =3D=3D QAPIDoc.Kind.TODO: # Hide TODO: sections continue =20 - if not section.tag: + if section.kind =3D=3D QAPIDoc.Kind.PLAIN: # Sphinx cannot handle sectionless titles; # Instead, just append the results to the prior section. container =3D nodes.container() @@ -270,7 +271,7 @@ def _nodes_for_sections(self, doc): nodelist +=3D container.children continue =20 - snode =3D self._make_section(section.tag) + snode =3D self._make_section(section.kind.name.title()) self._parse_text_into_node(dedent(section.text), snode) nodelist.append(snode) return nodelist diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index 36cb64a677a..c3004aa70c6 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -15,6 +15,7 @@ # See the COPYING file in the top-level directory. =20 from collections import OrderedDict +import enum import os import re from typing import ( @@ -575,7 +576,10 @@ def get_doc(self) -> 'QAPIDoc': ) raise QAPIParseError(self, emsg) =20 - doc.new_tagged_section(self.info, match.group(1)) + doc.new_tagged_section( + self.info, + QAPIDoc.Kind.from_string(match.group(1)) + ) text =3D line[match.end():] if text: doc.append_line(text) @@ -586,7 +590,7 @@ def get_doc(self) -> 'QAPIDoc': self, "unexpected '=3D' markup in definition documentati= on") else: - # tag-less paragraph + # plain paragraph(s) doc.ensure_untagged_section(self.info) doc.append_line(line) line =3D self.get_doc_paragraph(doc) @@ -635,14 +639,37 @@ class QAPIDoc: Free-form documentation blocks consist only of a body section. """ =20 + class Kind(enum.Enum): + PLAIN =3D 0 + MEMBER =3D 1 + FEATURE =3D 2 + RETURNS =3D 3 + ERRORS =3D 4 + SINCE =3D 5 + TODO =3D 6 + + @staticmethod + def from_string(kind: str) -> 'QAPIDoc.Kind': + return QAPIDoc.Kind[kind.upper()] + + def text_required(self) -> bool: + # Only "plain" sections can be empty + return self.value not in (0,) + + def __str__(self) -> str: + return self.name.title() + class Section: # pylint: disable=3Dtoo-few-public-methods - def __init__(self, info: QAPISourceInfo, - tag: Optional[str] =3D None): + def __init__( + self, + info: QAPISourceInfo, + kind: 'QAPIDoc.Kind', + ): # section source info, i.e. where it begins self.info =3D info - # section tag, if any ('Returns', '@name', ...) - self.tag =3D tag + # section kind + self.kind =3D kind # section text without tag self.text =3D '' =20 @@ -650,8 +677,14 @@ 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, + kind: 'QAPIDoc.Kind', + name: str + ): + super().__init__(info, kind) + self.name =3D name self.member: Optional['QAPISchemaMember'] =3D None =20 def connect(self, member: 'QAPISchemaMember') -> None: @@ -663,7 +696,9 @@ def __init__(self, info: QAPISourceInfo, symbol: Option= al[str] =3D None): # definition doc's symbol, None for free-form doc self.symbol: Optional[str] =3D symbol # the sections in textual order - self.all_sections: List[QAPIDoc.Section] =3D [QAPIDoc.Section(info= )] + self.all_sections: List[QAPIDoc.Section] =3D [ + QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN) + ] # the body section self.body: Optional[QAPIDoc.Section] =3D self.all_sections[0] # dicts mapping parameter/feature names to their description @@ -680,12 +715,17 @@ def __init__(self, info: QAPISourceInfo, symbol: Opti= onal[str] =3D None): def end(self) -> None: for section in self.all_sections: section.text =3D section.text.strip('\n') - if section.tag is not None and section.text =3D=3D '': + if section.kind.text_required() and section.text =3D=3D '': raise QAPISemError( - section.info, "text required after '%s:'" % section.ta= g) + section.info, "text required after '%s:'" % section.ki= nd) =20 - def ensure_untagged_section(self, info: QAPISourceInfo) -> None: - if self.all_sections and not self.all_sections[-1].tag: + def ensure_untagged_section( + self, + info: QAPISourceInfo, + ) -> None: + kind =3D QAPIDoc.Kind.PLAIN + + if self.all_sections and self.all_sections[-1].kind =3D=3D kind: # extend current section section =3D self.all_sections[-1] if not section.text: @@ -693,46 +733,56 @@ def ensure_untagged_section(self, info: QAPISourceInf= o) -> None: section.info =3D info section.text +=3D '\n' return + # start new section - section =3D self.Section(info) + section =3D self.Section(info, kind) self.sections.append(section) self.all_sections.append(section) =20 - def new_tagged_section(self, info: QAPISourceInfo, tag: str) -> None: - section =3D self.Section(info, tag) - if tag =3D=3D 'Returns': + def new_tagged_section( + self, + info: QAPISourceInfo, + kind: 'QAPIDoc.Kind', + ) -> None: + section =3D self.Section(info, kind) + if kind =3D=3D QAPIDoc.Kind.RETURNS: if self.returns: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.returns =3D section - elif tag =3D=3D 'Errors': + elif kind =3D=3D QAPIDoc.Kind.ERRORS: if self.errors: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.errors =3D section - elif tag =3D=3D 'Since': + elif kind =3D=3D QAPIDoc.Kind.SINCE: if self.since: raise QAPISemError( - info, "duplicated '%s' section" % tag) + info, "duplicated '%s' section" % kind) self.since =3D section self.sections.append(section) self.all_sections.append(section) =20 - def _new_description(self, info: QAPISourceInfo, name: str, - desc: Dict[str, ArgSection]) -> None: + def _new_description( + self, + info: QAPISourceInfo, + name: str, + kind: 'QAPIDoc.Kind', + 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, kind, name) 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, QAPIDoc.Kind.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, QAPIDoc.Kind.FEATURE, self.featu= res) =20 def append_line(self, line: str) -> None: self.all_sections[-1].append_line(line) @@ -744,8 +794,9 @@ 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) + section =3D QAPIDoc.ArgSection( + self.info, QAPIDoc.Kind.MEMBER, member.name) + self.args[member.name] =3D section self.args[member.name].connect(member) =20 def connect_feature(self, feature: 'QAPISchemaFeature') -> None: diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out index ec277be91e9..2d33a305ee7 100644 --- a/tests/qapi-schema/doc-good.out +++ b/tests/qapi-schema/doc-good.out @@ -110,7 +110,7 @@ The _one_ {and only}, description on the same line Also _one_ {and only} feature=3Denum-member-feat a member feature - section=3DNone + section=3DPlain @two is undocumented doc symbol=3DBase body=3D @@ -168,15 +168,15 @@ description starts on the same line a feature feature=3Dcmd-feat2 another feature - section=3DNone + section=3DPlain .. note:: @arg3 is undocumented section=3DReturns @Object section=3DErrors some - section=3DTODO + section=3DTodo frobnicate - section=3DNone + section=3DPlain .. admonition:: Notes =20 - Lorem ipsum dolor sit amet @@ -209,7 +209,7 @@ If you're bored enough to read this, go see a video of = boxed cats a feature feature=3Dcmd-feat2 another feature - section=3DNone + section=3DPlain .. qmp-example:: =20 -> "this example" diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py index 7e3f9f4aa1f..bca924309be 100755 --- a/tests/qapi-schema/test-qapi.py +++ b/tests/qapi-schema/test-qapi.py @@ -131,7 +131,7 @@ def test_frontend(fname): for feat, section in doc.features.items(): print(' feature=3D%s\n%s' % (feat, section.text)) for section in doc.sections: - print(' section=3D%s\n%s' % (section.tag, section.text)) + print(' section=3D%s\n%s' % (section.kind, section.text)) =20 =20 def open_test_result(dir_name, file_name, update): --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368355; cv=none; d=zohomail.com; s=zohoarc; b=fwjCd5ps9ODdJjpw9QgYsrFNikUs8qQcWoZXvrJljOu0UY/FFgFb6E+b76noPwaZVkp2zT52qv5sVOD3UtD695lWNQzOf0uWcE05rqmcCBP9okQwUQpZFXWU/r+7+7iZ9uZ3m6EujIXiH9Ke200f+AUuyo1Rl22F6uPwJqZ0Pgs= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368355; 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=VP5SDk4WkmLEFDLuA4c7QRtXKXfuW84WFZb7/tKq7PU=; b=nH6rTEp5dD/QBjeEYWJo+k0fFEZQuyn/Fko/hxaWVgnXIx4iqMSE+L+4trSIvfeCV+UpuZD0ABVVPqVJBGUwb3pN/Enx06Ri6jvIFzQPEUVGo/sIUX7Djv9tmuxpJGfw/bHFelUh223pAM1GsVSNQmVIp20guJ68Sy28M0Tih5Y= 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 17403683558968.717997538466875; Sun, 23 Feb 2025 19:39:15 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPJ1-00020g-OA; Sun, 23 Feb 2025 22:38:57 -0500 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 1tmPIK-0001Px-VU for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:15 -0500 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 1tmPIH-0005Rl-VU for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:12 -0500 Received: from mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-589-AuHs_yNeMkCbz69CtkaH8g-1; Sun, 23 Feb 2025 22:38:04 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B406318EB2C6; Mon, 24 Feb 2025 03:38:03 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id D97D919560A3; Mon, 24 Feb 2025 03:38:01 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368289; 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=VP5SDk4WkmLEFDLuA4c7QRtXKXfuW84WFZb7/tKq7PU=; b=acde/lPeJl3LOpCt2V578OZ0i7bJ1l6KzpYe7isMuXNcX864ZW9xJOOK4dkhKKMlhY/afz plTVfK8ueHRthksL578sKniusUCtjkjrp2iHOnM32rdbKU0/CZDveomTI9H7n1aG4v+2De Y8ioBtWi9mHhhsTX2bIym4pbq8nsYFg= X-MC-Unique: AuHs_yNeMkCbz69CtkaH8g-1 X-Mimecast-MFC-AGG-ID: AuHs_yNeMkCbz69CtkaH8g_1740368283 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 08/10] qapi/schema: add __repr__ to QAPIDoc.Section Date: Sun, 23 Feb 2025 22:37:39 -0500 Message-ID: <20250224033741.222749-9-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=-1, RCVD_IN_MSPIKE_WL=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368357529019100 Content-Type: text/plain; charset="utf-8" Makes debugging far more pleasant when you can just print(section) and get something reasonable to display. Signed-off-by: John Snow --- scripts/qapi/parser.py | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py index c3004aa70c6..617711b1f04 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -673,6 +673,9 @@ def __init__( # section text without tag self.text =3D '' =20 + def __repr__(self) -> str: + return f"" + def append_line(self, line: str) -> None: self.text +=3D line + '\n' =20 @@ -687,6 +690,12 @@ def __init__( self.name =3D name self.member: Optional['QAPISchemaMember'] =3D None =20 + def __repr__(self) -> str: + return ( + f"" + ) + def connect(self, member: 'QAPISchemaMember') -> None: self.member =3D member =20 --=20 2.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368366; cv=none; d=zohomail.com; s=zohoarc; b=kJnkztirtKHBC+A1MndoJqTquwr89fy534xns0ZB3kfPl1PTTRRsijHTS+w8uQwNeUh1U9TeY1J5H7zQ+5/cQunFyq/06RK/iTF5Zp77bkDb2RTTATkF3D175nramIW6xduav8X2cbKlR5lB1MADVuRH2FQzMK7KpgVu2YT9F3w= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368366; 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=7G6YVAL0iU98F5nK+nS2ppNms52d37aU3+2UhKmOzzI=; b=DAo1fMjj+a5+33wzsTwsggyaF27pXjVuab8W201QQOxuoCA1EQlVr7PaD6h5LkkG4kvvS0uLdRmYK1pQedNo8ULpRXfHi2ZaZumFrTsQywJ8YLa8IvxJLPJH+URo93rX83X1pWGliZAJfg9+4Ox5sZzI9ockW85QrRTpPp9B4pE= 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 1740368366941946.7562358505863; Sun, 23 Feb 2025 19:39:26 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIo-0001hw-D9; Sun, 23 Feb 2025 22:38:43 -0500 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 1tmPIN-0001Q2-9G for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:15 -0500 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 1tmPIK-0005Rr-P6 for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:14 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-294-CjF-6A1pMSGGNL7KsbCRFw-1; Sun, 23 Feb 2025 22:38:06 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id C66CB18004A7; Mon, 24 Feb 2025 03:38:05 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 0192E19560A3; Mon, 24 Feb 2025 03:38:03 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368290; 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=7G6YVAL0iU98F5nK+nS2ppNms52d37aU3+2UhKmOzzI=; b=Hr7j5UAD2LEZ2+hZwT1CbgiM8B++8ryR6OZylZpjhSWvzKfx5s8upSI9xK3T0RJ6BR858r /1z8L5qCu/LSc4ACSUATWgwXwfTIOqVNq3Sm6VTNH5cLaWOn7zv2yI5Dmqpt2SrgedPh/u 7ikMML/XutMygYECDkCwB3z39+ZHiJU= X-MC-Unique: CjF-6A1pMSGGNL7KsbCRFw-1 X-Mimecast-MFC-AGG-ID: CjF-6A1pMSGGNL7KsbCRFw_1740368285 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 09/10] qapi/source: allow multi-line QAPISourceInfo advancing Date: Sun, 23 Feb 2025 22:37:40 -0500 Message-ID: <20250224033741.222749-10-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, 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_H2=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368367617019100 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. This is used mainly when converting section syntax in free-form documentation to more traditional rST section header syntax, which does not always line up 1:1 for line counts. For example: ``` ## # =3D Section <-- Info is pointing here, "L1" # # Lorem Ipsum ## ``` would be transformed to rST by the transmogrifier as: ``` =3D=3D=3D=3D=3D=3D=3D <-- L1 Section <-- L1 =3D=3D=3D=3D=3D=3D=3D <-- L1 <-- L2 Lorem Ipsum <-- L3 ``` With each line having its own source information credited to different source lines; sometimes one line to many. After consuming the single "Section" line from the source, we want to advance the source pointer to the next non-empty line which requires jumping by more than one line. ``` ## # =3D Section <-- Info is pointing here, "L1" # # Lorem Ipsum <-- We want to jump to here, +2. ## ``` Signed-off-by: John Snow Reviewed-by: Markus Armbruster --- 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.48.1 From nobody Thu Apr 3 09:59:32 2025 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=1740368364; cv=none; d=zohomail.com; s=zohoarc; b=Z4UoJKt4gpCZ2J/+PvRMF1ZHptzXYvLYHQF/osD5Ee5EvVjkQKYdvE7pg4jq8hCLeugVFR+Q951e9Ebe8Q/4TlYLLVcbVjE3ELrFYo47nnLV+cNfpZqguKFeL3+bOfctPEU+U9Owv9KEDo80vExteVZCwqwiBWK4Zjn9FTAon8k= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1740368364; 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=NbNayGZzT5MkWdIwYFTlZTtHA+MFXV5ILRIOuKh2nCU=; b=NldCDlDjImwIai/UsAcuBKbDiQ2x2cuAFs4IV9RVvj61grhxdm421abEYwEpb94a+L42LDPm0b/NrlXn1Fx7PpE5Aa9MGefJbdX2fM1C1YXZ0w7x0di0YyYSLQeU9Kg36WMWBjXEUHotpPjDk0VpWgJPaWWqQn322k/k4Nlq7b8= 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 1740368364144739.3952788042933; Sun, 23 Feb 2025 19:39:24 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tmPIp-0001iu-Nq; Sun, 23 Feb 2025 22:38:43 -0500 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 1tmPIO-0001Qc-VU for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:19 -0500 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 1tmPIM-0005S5-OF for qemu-devel@nongnu.org; Sun, 23 Feb 2025 22:38:16 -0500 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-694-we2NwQSvMS28V5v6NkXWxQ-1; Sun, 23 Feb 2025 22:38:09 -0500 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DBD361800873; Mon, 24 Feb 2025 03:38:07 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.88]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 168FF19560A3; Mon, 24 Feb 2025 03:38:05 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1740368292; 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=NbNayGZzT5MkWdIwYFTlZTtHA+MFXV5ILRIOuKh2nCU=; b=XgUl6CKCJSf1PRF8A7xTHpsUkcfHMVpRfOikh7TvXrOQLoUtCSO8YcRQcXQUSq40wFLCb4 FSsZTXzlpZmHXv5HX4eCsf7WExj9y1QR0E5oh1Q+yzedYUcgGkv0KyNaqReqkLuqtA24Md n4DaP8Wur71LFk/x2KTe8ED9kFwkt00= X-MC-Unique: we2NwQSvMS28V5v6NkXWxQ-1 X-Mimecast-MFC-AGG-ID: we2NwQSvMS28V5v6NkXWxQ_1740368288 From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Thomas Huth , Peter Maydell , Markus Armbruster , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Cleber Rosa , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= Subject: [PATCH 10/10] docs: disambiguate cross-references Date: Sun, 23 Feb 2025 22:37:41 -0500 Message-ID: <20250224033741.222749-11-jsnow@redhat.com> In-Reply-To: <20250224033741.222749-1-jsnow@redhat.com> References: <20250224033741.222749-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=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: -25 X-Spam_score: -2.6 X-Spam_bar: -- X-Spam_report: (-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.446, 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_H2=-0.01, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=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: 1740368365665019100 Content-Type: text/plain; charset="utf-8" These references are not in and of themselves problems at the moment, however, the forthcoming qapidoc conversion series will begin adding cross-reference targets that conflict with these existing targets. As a result, cross-references such as "migration", "qom", "replay" will become ambiguous. Modify these references to be more explicit to prevent "ambiguous cross-reference" warnings in the future. Signed-off-by: John Snow --- docs/devel/codebase.rst | 6 +++--- docs/glossary.rst | 10 +++++----- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/devel/codebase.rst b/docs/devel/codebase.rst index 4039875ee04..1b09953197b 100644 --- a/docs/devel/codebase.rst +++ b/docs/devel/codebase.rst @@ -23,7 +23,7 @@ Some of the main QEMU subsystems are: - `Devices` & Board models - `Documentation ` - `GDB support` -- `Migration` +- :ref:`Migration` - `Monitor` - :ref:`QOM (QEMU Object Model)` - `System mode` @@ -112,7 +112,7 @@ yet, so sometimes the source code is all you have. * `libdecnumber `_: Import of gcc library, used to implement decimal number arithmetic. * `migration `__: - `Migration framework `. + :ref:`Migration framework `. * `monitor `_: `Monitor ` implementation (HMP & QMP). * `nbd `_: @@ -193,7 +193,7 @@ yet, so sometimes the source code is all you have. - `lcitool `_: Generate dockerfiles for CI containers. - `migration `_: - Test scripts and data for `Migration framework `. + Test scripts and data for :ref:`Migration framework `. - `multiboot `_: Test multiboot functionality for x86_64/i386. - `qapi-schema `_: diff --git a/docs/glossary.rst b/docs/glossary.rst index 693d9855dd1..4fa044bfb6e 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -120,7 +120,7 @@ Migration --------- =20 QEMU can save and restore the execution of a virtual machine between diffe= rent -host systems. This is provided by the `Migration framework`. +host systems. This is provided by the :ref:`Migration framework= `. =20 NBD --- @@ -212,14 +212,14 @@ machine emulator and virtualizer. QOM --- =20 -`QEMU Object Model ` is an object oriented API used to define various -devices and hardware in the QEMU codebase. +:ref:`QEMU Object Model ` is an object oriented API used to define +various devices and hardware in the QEMU codebase. =20 Record/replay ------------- =20 -`Record/replay ` is a feature of QEMU allowing to have a determini= stic -and reproducible execution of a virtual machine. +:ref:`Record/replay ` is a feature of QEMU allowing to have a +deterministic and reproducible execution of a virtual machine. =20 Rust ---- --=20 2.48.1