From nobody Fri Apr 4 03:33:00 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=1741947160; cv=none; d=zohomail.com; s=zohoarc; b=nOoE5Ck6jylTWW8aHA6NOWmimnIcQGV6Qtntm8Qqsqdxv8mHHox2AL/H9wWYh03mvDl0SVXSDuPQ2DwN37pWwdDWEEuvSdHP7Bm8y5vWuSjLV9saHbQ2/x6kv4rBvtlJVlBJ/mkKvhne2iaS+fBoxF8Dz5WrE//K/yYJVNVJnCk= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947160; 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=9DM5gO/mHUWf4r2tQdDbJnbbTizjhichNpsmghIv8zE=; b=Uuzz+zeXf+kAxXzZD4W7w3Me00vMHigQxjwL64OT2xvaSeN51Uot+8V2koq7rKWTll39LZzxuZYMf19LSitkNsahjS8csv/m/rw26jCNgjxBIuXsmI/EkhZgv+ygURG6kZ6Su3OV2V/2w0wjB/rC7dqMezhl78Oeav3+gXGkLdY= 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 1741947160832256.7159432883776; Fri, 14 Mar 2025 03:12:40 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20L-0006KI-Js; Fri, 14 Mar 2025 06:11:01 -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 1tt20B-0006I5-Mt for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:52 -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 1tt208-00021v-C4 for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:51 -0400 Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-517-WKNsrGDkMpKaTVJU0JLGFA-1; Fri, 14 Mar 2025 06:10:46 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 21F1419560B6; Fri, 14 Mar 2025 10:10:44 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8BE7918001DE; Fri, 14 Mar 2025 10:10:43 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id B9A0521E669B; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947047; 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=9DM5gO/mHUWf4r2tQdDbJnbbTizjhichNpsmghIv8zE=; b=T9eJ4SIQHP6zu2DYbD+aeaVRTH7BwPoC9eHeXvPCM1z0LmJAPQYRw7ZuAqzuk8Tl/SjEwS 3HPb3TQsXjod8tV7j4inBxaxoUPz36//HNyRqR7NnIOSfUlihNq9awx51soxzAvFhk8KZ3 KdDjZsQ95gmOZ1/Yv10KOFeqTQdPSCA= X-MC-Unique: WKNsrGDkMpKaTVJU0JLGFA-1 X-Mimecast-MFC-AGG-ID: WKNsrGDkMpKaTVJU0JLGFA_1741947045 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, Alberto Garcia Subject: [PULL 01/12] qapi/block-core: Improve x-blockdev-change documentation Date: Fri, 14 Mar 2025 11:10:27 +0100 Message-ID: <20250314101038.2408751-2-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947163816019100 Content-Type: text/plain; charset="utf-8" The description of feature @unstable is three paragraphs. The second and third became part of the description by accident in commit 9fb49daabfb (qapi: Mark unstable QMP parts with feature 'unstable'). The second paragraph describes a defect in terms of the implementation. Fine, but doesn't belong into user-facing documentation. Turn it into a TODO section. Rewrite everything else for clarity and completeness. Signed-off-by: Markus Armbruster Message-ID: <20250311131715.1296101-1-armbru@redhat.com> Acked-by: Alberto Garcia --- qapi/block-core.json | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index ee6eccc68c..b1937780e1 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -5913,35 +5913,31 @@ ## # @x-blockdev-change: # -# Dynamically reconfigure the block driver state graph. It can be -# used to add, remove, insert or replace a graph node. Currently only -# the Quorum driver implements this feature to add or remove its -# child. This is useful to fix a broken quorum child. +# Dynamically reconfigure the block driver state graph. # -# If @node is specified, it will be inserted under @parent. @child -# may not be specified in this case. If both @parent and @child are -# specified but @node is not, @child will be detached from @parent. +# Currently only supports adding and deleting quorum children. A +# child will be added at the end of the list of children. Its +# contents *must* be consistent with the other childrens' contents. +# Deleting a child that is not last in the list of children is +# problematic, because it "renumbers" the children following it. # # @parent: the id or name of the parent node. # -# @child: the name of a child under the given parent node. +# @child: the name of a child to be deleted. Mutually exclusive with +# @node. # -# @node: the name of the node that will be added. +# @node: the name of the node to be added. Mutually exclusive with +# @child. # # Features: # -# @unstable: This command is experimental, and its API is not stable. -# It does not support all kinds of operations, all kinds of -# children, nor all block drivers. +# @unstable: This command is experimental. # -# FIXME Removing children from a quorum node means introducing +# TODO: Removing children from a quorum node means introducing # gaps in the child indices. This cannot be represented in the # 'children' list of BlockdevOptionsQuorum, as returned by # .bdrv_refresh_filename(). # -# Warning: The data in a new quorum child MUST be consistent with -# that of the rest of the array. -# # Since: 2.7 # # .. qmp-example:: --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947106; cv=none; d=zohomail.com; s=zohoarc; b=DSqmRLyH4MBkR+OH1u4Twmd60tNFKPR93ujyaOoQwY9AO0JhMNarXwLHhd0GSTRNBNtH+UB6S7cOcIg0Q5b0pzZ6o0Ds9f/+epoBS3iuJ+UVeSPmxE1GLRsBcZTPq0J16/xLmt6BpXrK9BgDsHhWhq1rLHy5xPT7QP8/F+HhhvY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947106; 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=bxgvXu/x8itjefbAnHJcPTUQUR6+sgtoyE3sKaeR4Gg=; b=PeVwtDE3//5aye9RwGDNJfNWqps6+/3SIgh0ohO6PtmYgEbGpvqw2NC++kHe8W9Jpkgp/qhVb8ADzR5lYf+VpJXT8yvAjlj4q0M5FhbSFAktL++/Y/uwHrOQjROOb+xQPiO8+InTOmOZgAZJgxz6cDKv3JTVGpSRf3xvBywlfEs= 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 1741947106697302.08853804644673; Fri, 14 Mar 2025 03:11:46 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20K-0006J4-Tl; Fri, 14 Mar 2025 06:11:01 -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 1tt20B-0006I7-T2 for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:52 -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 1tt208-00021y-NS for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:51 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-434-oDCcOe2vMICIHmmzjoylng-1; Fri, 14 Mar 2025 06:10:45 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 6C56B180036E for ; Fri, 14 Mar 2025 10:10:44 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 012AC300377A for ; Fri, 14 Mar 2025 10:10:43 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BE36021E669D; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947047; 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=bxgvXu/x8itjefbAnHJcPTUQUR6+sgtoyE3sKaeR4Gg=; b=GvuTdwyiz2McA+fZo9xvlHBlJoo0lFdN634PHPAVJlGChR8XtTYryLIIBZeBBbN+8NF0GI 3urHDNYtgQhsbtkdk5IPrIZRr2arrYU7TXzd6zprpx/bvRmcd13yJux/N8ALuRx8YSMz0a hH/oNgd/sxfx6TRTdjdwMtgW1G6Qa5k= X-MC-Unique: oDCcOe2vMICIHmmzjoylng-1 X-Mimecast-MFC-AGG-ID: oDCcOe2vMICIHmmzjoylng_1741947044 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 02/12] docs/qapi_domain: isolate TYPE_CHECKING imports Date: Fri, 14 Mar 2025 11:10:28 +0100 Message-ID: <20250314101038.2408751-3-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947107777019000 Content-Type: text/plain; charset="utf-8" From: John Snow When using the annotations feature, type hints do not need to be imported at runtime, only at type check time. Move type-check-only imports into a conditional to reduce the number of imports needed at runtime. Signed-off-by: John Snow Message-ID: <20250313044312.189276-2-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 7ff618d8cd..d52e7df7bc 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -9,15 +9,9 @@ =20 from typing import ( TYPE_CHECKING, - AbstractSet, - Any, - Dict, - Iterable, List, NamedTuple, - Optional, Tuple, - Union, cast, ) =20 @@ -34,7 +28,6 @@ SpaceNode, ) from sphinx import addnodes -from sphinx.addnodes import desc_signature, pending_xref from sphinx.directives import ObjectDescription from sphinx.domains import ( Domain, @@ -49,13 +42,24 @@ =20 =20 if TYPE_CHECKING: + from typing import ( + AbstractSet, + Any, + Dict, + Iterable, + Optional, + Union, + ) + from docutils.nodes import Element, Node =20 + from sphinx.addnodes import desc_signature, pending_xref from sphinx.application import Sphinx from sphinx.builders import Builder from sphinx.environment import BuildEnvironment from sphinx.util.typing import OptionSpec =20 + logger =3D logging.getLogger(__name__) =20 =20 --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947107; cv=none; d=zohomail.com; s=zohoarc; b=R+i5ybufL8suWgPA/yK8d0Dupi4GbYr1IeRTqVuNkf6nta5gINI1KAriBQCEZ9kH8uT6xSXLNsZ0dDZhid1NIO7U71ZfG39i0b6j26r1EA9mUPOBBzWdyAbT3+vYRO/4D6DlXUa8Ai5lQqOGO8UZoUrvmvftbA1e7ZbImzIMzwQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947107; 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=BJOvE7bX3CbiaJXP+Wn72i13qtqWhY5+bX0nNEwCku8=; b=G6ZQIc01hH22HfzU+tsrHAvGBZ6Q3lhjxA3X+6Jbh9j6Hpcsx7rV6/AW7F2sIWSLMmL9OuydXNpPDTUAfa5qaUD247znciHRRYgO4iMTfxU6BUZ4RqcFI0S4s1FvnIZE71jg3iF7jhG3GWo33OOQ1aTC2OfMtuL/qv6Is/JniHg= 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 1741947107697226.43777931871034; Fri, 14 Mar 2025 03:11:47 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20L-0006KM-Tc; Fri, 14 Mar 2025 06:11:01 -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 1tt20G-0006Iv-1F for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -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 1tt20C-00023R-SH for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:55 -0400 Received: from mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-219-Gi5cm--mNlmrsg8fDDYeLA-1; Fri, 14 Mar 2025 06:10:45 -0400 Received: from mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.4]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E935B19560B8 for ; Fri, 14 Mar 2025 10:10:44 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-01.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E0EF2300376F for ; Fri, 14 Mar 2025 10:10:43 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C257B21E66A3; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=BJOvE7bX3CbiaJXP+Wn72i13qtqWhY5+bX0nNEwCku8=; b=Z0DcZ6gO0g0YtkaqCZ25zLBJ2ApKS26yGLFGB5usSPtGNIcEJimXW47iS9Buluo0JX2k2b npUztyyq9mqskFxZFrJLfjFSaYz/xTS3vgIruCVE/zkIFEEheNxV5Mr7w2uuv+7xzoO67J IzYjEOlU/Drun0rnusflIMxnRPZeh90= X-MC-Unique: Gi5cm--mNlmrsg8fDDYeLA-1 X-Mimecast-MFC-AGG-ID: Gi5cm--mNlmrsg8fDDYeLA_1741947045 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 03/12] docs/qapi-domain: always store fully qualified name in signode Date: Fri, 14 Mar 2025 11:10:29 +0100 Message-ID: <20250314101038.2408751-4-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.4 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947109835019100 Content-Type: text/plain; charset="utf-8" From: John Snow Currently, only the definition name is stored in the tree metadata; but the node property is confusingly called "fullname". Rectify this by always storing the FQN in the tree metadata. ... While we're here, re-organize the code in preparation for namespace support to make it a bit easier to add additional components of the FQN. With this change, there is now extremely little code left that's taken directly from the Python domain :) Signed-off-by: John Snow Message-ID: <20250313044312.189276-3-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 64 +++++++++++++++++++++++++------------- 1 file changed, 42 insertions(+), 22 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index d52e7df7bc..6b23fc73ef 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -178,6 +178,25 @@ def get_index_text(self, name: Signature) -> Tuple[str= , str]: # NB: this is used for the global index, not the QAPI index. return ("single", f"{name} (QMP {self.objtype})") =20 + def _get_context(self) -> str: + modname =3D self.options.get( + "module", self.env.ref_context.get("qapi:module", "") + ) + assert isinstance(modname, str) + return modname + + def _get_fqn(self, name: Signature) -> str: + modname =3D self._get_context() + + # If we're documenting a module, don't include the module as + # part of the FQN; we ARE the module! + if self.objtype =3D=3D "module": + modname =3D "" + + if modname: + name =3D f"{modname}.{name}" + return name + def add_target_and_index( self, name: Signature, sig: str, signode: desc_signature ) -> None: @@ -187,14 +206,8 @@ def add_target_and_index( =20 assert self.objtype =20 - # If we're documenting a module, don't include the module as - # part of the FQN. - modname =3D "" - if self.objtype !=3D "module": - modname =3D self.options.get( - "module", self.env.ref_context.get("qapi:module") - ) - fullname =3D (modname + "." if modname else "") + name + if not (fullname :=3D signode.get("fullname", "")): + fullname =3D self._get_fqn(name) =20 node_id =3D make_id( self.env, self.state.document, self.objtype, fullname @@ -213,18 +226,21 @@ def add_target_and_index( (arity, indextext, node_id, "", None) ) =20 + @staticmethod + def split_fqn(name: str) -> Tuple[str, str]: + if "." in name: + module, name =3D name.split(".") + else: + module =3D "" + + return (module, name) + def _object_hierarchy_parts( self, sig_node: desc_signature ) -> Tuple[str, ...]: if "fullname" not in sig_node: return () - modname =3D sig_node.get("module") - fullname =3D sig_node["fullname"] - - if modname: - return (modname, *fullname.split(".")) - - return tuple(fullname.split(".")) + return self.split_fqn(sig_node["fullname"]) =20 def _toc_entry_name(self, sig_node: desc_signature) -> str: # This controls the name in the TOC and on the sidebar. @@ -235,13 +251,19 @@ def _toc_entry_name(self, sig_node: desc_signature) -= > str: return "" =20 config =3D self.env.app.config - *parents, name =3D toc_parts + modname, name =3D toc_parts + if config.toc_object_entries_show_parents =3D=3D "domain": - return sig_node.get("fullname", name) + ret =3D name + if modname and modname !=3D self.env.ref_context.get( + "qapi:module", "" + ): + ret =3D f"{modname}.{name}" + return ret if config.toc_object_entries_show_parents =3D=3D "hide": return name if config.toc_object_entries_show_parents =3D=3D "all": - return ".".join(parents + [name]) + return sig_node.get("fullname", name) return "" =20 =20 @@ -312,11 +334,9 @@ def handle_signature(self, sig: str, signode: desc_sig= nature) -> Signature: As such, the only argument here is "sig", which is just the QAPI definition name. """ - modname =3D self.options.get( - "module", self.env.ref_context.get("qapi:module") - ) + modname =3D self._get_context() =20 - signode["fullname"] =3D sig + signode["fullname"] =3D self._get_fqn(sig) signode["module"] =3D modname sig_prefix =3D self.get_signature_prefix() if sig_prefix: --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947123; cv=none; d=zohomail.com; s=zohoarc; b=YN296HnmJAqEOLki1a1fW4I/Dqj3pmXFtYceox36DhXL7V+TVE6ai3eXtNaQ1mLGmgwKZDPxJnDrxBS1Q8iNEF07gERbhc7ybB+obotdj7WHGmtLl4YX4m06wm4lqrevpMqBr5tZvhPn98Ow7mDvswxSXTzqLgQKIFvDnKhR08c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947123; 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=L6K58Cl2kQo8RwkeszDmBOm0EdqS+sV+IffyEcy9VvA=; b=WTDFxzld5zYKuvW7jOByGjWF5vuqqeEHyBMr58CGd9eWsmTSd03X9oTpgxKpvz6j1BlOWrzZAfB2cDygF+q0kP65POpJHIsOP/mSyjLIvJZSykBjjIhTEu6q8EpCYyoZUAUms+oV0Znv1yYVII45P8Tqopof2RU08LrDxBiW/2E= 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 1741947123307427.2631548574369; Fri, 14 Mar 2025 03:12:03 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20E-0006Ie-Gz; Fri, 14 Mar 2025 06:10:55 -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 1tt20A-0006Hj-MZ for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:50 -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 1tt208-00021l-0U for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:50 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-352-gRnyYzAQMcqJTk9iHuRRcw-1; Fri, 14 Mar 2025 06:10:45 -0400 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 4277C180025A for ; Fri, 14 Mar 2025 10:10:44 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B236B1955BCB for ; Fri, 14 Mar 2025 10:10:43 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C676F21E66A4; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947046; 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=L6K58Cl2kQo8RwkeszDmBOm0EdqS+sV+IffyEcy9VvA=; b=I80qXmiQOjO0zvkw7txnWNHwqJFv0rKqPNWmXKtPDU8w7tG9ErVd5/Rl+MudXyTlQY405j sp+tjnvYqh9Pw0Auqi4MWsT5YtjH+l6bGZJ78zTnK7Ygq4hbS/1mp3NmVBju/cpr5daRWq fPcAeb6FgI16iIgRYqw+fij9n1/yN7s= X-MC-Unique: gRnyYzAQMcqJTk9iHuRRcw-1 X-Mimecast-MFC-AGG-ID: gRnyYzAQMcqJTk9iHuRRcw_1741947044 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 04/12] docs/qapi_domain: add namespace support to FQN Date: Fri, 14 Mar 2025 11:10:30 +0100 Message-ID: <20250314101038.2408751-5-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947123830019000 Content-Type: text/plain; charset="utf-8" From: John Snow This patch adds a namespace component to the "Fully Qualified Name", in the form of "domain:module.name". As there are no namespace directives or options yet, this component will simply be empty as of this patch. Signed-off-by: John Snow Message-ID: <20250313044312.189276-4-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 35 +++++++++++++++++++++++++++-------- 1 file changed, 27 insertions(+), 8 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 6b23fc73ef..48a082d489 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -178,15 +178,18 @@ def get_index_text(self, name: Signature) -> Tuple[st= r, str]: # NB: this is used for the global index, not the QAPI index. return ("single", f"{name} (QMP {self.objtype})") =20 - def _get_context(self) -> str: + def _get_context(self) -> Tuple[str, str]: + namespace =3D self.options.get( + "namespace", self.env.ref_context.get("qapi:namespace", "") + ) modname =3D self.options.get( "module", self.env.ref_context.get("qapi:module", "") ) - assert isinstance(modname, str) - return modname + + return namespace, modname =20 def _get_fqn(self, name: Signature) -> str: - modname =3D self._get_context() + namespace, modname =3D self._get_context() =20 # If we're documenting a module, don't include the module as # part of the FQN; we ARE the module! @@ -195,6 +198,8 @@ def _get_fqn(self, name: Signature) -> str: =20 if modname: name =3D f"{modname}.{name}" + if namespace: + name =3D f"{namespace}:{name}" return name =20 def add_target_and_index( @@ -227,13 +232,18 @@ def add_target_and_index( ) =20 @staticmethod - def split_fqn(name: str) -> Tuple[str, str]: + def split_fqn(name: str) -> Tuple[str, str, str]: + if ":" in name: + ns, name =3D name.split(":") + else: + ns =3D "" + if "." in name: module, name =3D name.split(".") else: module =3D "" =20 - return (module, name) + return (ns, module, name) =20 def _object_hierarchy_parts( self, sig_node: desc_signature @@ -251,7 +261,7 @@ def _toc_entry_name(self, sig_node: desc_signature) -> = str: return "" =20 config =3D self.env.app.config - modname, name =3D toc_parts + namespace, modname, name =3D toc_parts =20 if config.toc_object_entries_show_parents =3D=3D "domain": ret =3D name @@ -259,6 +269,10 @@ def _toc_entry_name(self, sig_node: desc_signature) ->= str: "qapi:module", "" ): ret =3D f"{modname}.{name}" + if namespace and namespace !=3D self.env.ref_context.get( + "qapi:namespace", "" + ): + ret =3D f"{namespace}:{ret}" return ret if config.toc_object_entries_show_parents =3D=3D "hide": return name @@ -334,10 +348,15 @@ def handle_signature(self, sig: str, signode: desc_si= gnature) -> Signature: As such, the only argument here is "sig", which is just the QAPI definition name. """ - modname =3D self._get_context() + # No module or domain info allowed in the signature! + assert ":" not in sig + assert "." not in sig =20 + namespace, modname =3D self._get_context() signode["fullname"] =3D self._get_fqn(sig) + signode["namespace"] =3D namespace signode["module"] =3D modname + sig_prefix =3D self.get_signature_prefix() if sig_prefix: signode +=3D addnodes.desc_annotation( --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947189; cv=none; d=zohomail.com; s=zohoarc; b=iPkTVZQbJiNDHy2Xbo8ol/2265ELboYET26BUkJyeAsoeYlSbRyyPbUJPzw9MN9LeCSpAvKLZeKaERIeTmfqJo0ZcDoKxNo/zTJXsuuv181bQMsHEJL8/eAr/mQLauIqmDRxpJ1Geg2oYr4JV6cgaMMLoraRGwIrZ/BVK/M1WbE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947189; 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=6aqwbTO8KT37DTKD835oXBUCkA/jttLd966RrPuvFV0=; b=lLq7SiE4E2fuma3B8mj6HBfBwlkH37NkK/0V2+VPLfN4oBeAKo/LoqXOkAXWJZWwpeazlV9KH11De8zGI1HuDOPegPHTETp1tNFtd/EueciI+meT7C0oae+T9NdimCavl6XHiB7r6DDOuWoYPZKpRCFtqYf7rL9Xg29vFqAj/bA= 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 1741947189505691.9600593941258; Fri, 14 Mar 2025 03:13:09 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20M-0006KZ-CM; Fri, 14 Mar 2025 06:11:02 -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 1tt20E-0006If-CP for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -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 1tt20C-00022q-Lw for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-246-q0MjlDDFOOOgn01-psRswA-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DF8BE180035C for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 88CAF1828A98 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CA94A21E66A7; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947050; 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=6aqwbTO8KT37DTKD835oXBUCkA/jttLd966RrPuvFV0=; b=MRW9gt8ZFb0P3ZHFe4/Lb2lhnMZfeTCpnojiGjJJe5CKwyKks2k9MT6AmD9pSNPQEewmnh pWbUM6fN7W/+ho7HtwDOfx6wE/IFy6wLYm01t41C6X/JM3HchdgOUx+j6yhTZgURph1Qzu I2r9k37NdJnrnIOhK8rZY3a+bl62+n0= X-MC-Unique: q0MjlDDFOOOgn01-psRswA-1 X-Mimecast-MFC-AGG-ID: q0MjlDDFOOOgn01-psRswA_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 05/12] docs/qapi-domain: add :namespace: override option Date: Fri, 14 Mar 2025 11:10:31 +0100 Message-ID: <20250314101038.2408751-6-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947191840019100 Content-Type: text/plain; charset="utf-8" From: John Snow Akin to the :module: override option, the :namespace: options allows you to forcibly override the contextual namespace associatied with a definition. We don't necessarily actually need this, but I felt compelled to stick close to how the Python domain works that offers context overrides. As of this commit, it is possible to add e.g. ":namespace: QMP" to any QAPI directive to forcibly associate that definition with a given namespace. Signed-off-by: John Snow Message-ID: <20250313044312.189276-5-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 2 ++ docs/sphinx/qapi_domain.py | 5 +++-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 1475870ca6..51b283277e 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -466,6 +466,8 @@ QAPI standard options =20 All QAPI directives -- *except* for module -- support these common options. =20 +* ``:namespace: name`` -- This option allows you to override the + namespace association of a given definition. * ``:module: modname`` -- Borrowed from the Python domain, this option all= ows you to override the module association of a given definition. * ``:since: x.y`` -- Allows the documenting of "Since" information, which = is diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 48a082d489..6485c43206 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -294,8 +294,9 @@ class QAPIObject(QAPIDescription): ) option_spec.update( { - # Borrowed from the Python domain: - "module": directives.unchanged, # Override contextual module = name + # Context overrides: + "namespace": directives.unchanged, + "module": directives.unchanged, # These are QAPI originals: "since": directives.unchanged, "ifcond": directives.unchanged, --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947149; cv=none; d=zohomail.com; s=zohoarc; b=dnixX5e5FIIm83L4FdDDACQsOOlMRhHIwt0SfBL5ylwPoauL2cCwsGsSOqp6rDNYgPnnQ3/2fOc/wwwEyqAGu/5R6Qfs5M8FH5ucPAFI19sCGqglOZnqvHP4UV2cZ3C1Jn8afpg79e2O7tHfy/woBrOl06kx8oRoXIv5pjec8Xo= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947149; 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=zWM1J8OeYn4zhTwTnsdWw/CoR6nDQNvxa69361V/d1A=; b=i9+0O17Tkh2b9Y5iJsZBpsyuW3ErCP/f4MigFuC2CHkPeJXYKZnyN60Riz9+b9+4uPUdaH0SVa3NRbI/U9KXFTPCPpsP3tqtP58Yxhk4NYBXKmnTU20/fEMhBUjf+y0gD6icBW5hW2tcStiIwCCnlWPuo5XRcKoeHYwmSimuBrA= 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 1741947149465870.2006495116602; Fri, 14 Mar 2025 03:12:29 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20N-0006Km-4J; Fri, 14 Mar 2025 06:11:03 -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 1tt20G-0006JQ-HP for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:58 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tt20C-00022z-Vu for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -0400 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-558-sGEgBa_8OoaA5EI8toKpHg-1; Fri, 14 Mar 2025 06:10:50 -0400 Received: from mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.17]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 413B21956087 for ; Fri, 14 Mar 2025 10:10:49 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id DAF361955F2D for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id CE92E21E65DD; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=zWM1J8OeYn4zhTwTnsdWw/CoR6nDQNvxa69361V/d1A=; b=fz0+INCqfcUB9J5QwK/yFo2NrxZVPHTlWVell6yPYtKSbIs1TGXbPTqR48EiBqSCrBAj80 QR4HnO+qtR/WVRPUea2pxkFAA34u+qzYR+yM/WIkUCe5IKB/diPuQRR9DRJcuufGrLaSSo sKNWcA50bLFVsf/wsM2XMEPpJpD//6Y= X-MC-Unique: sGEgBa_8OoaA5EI8toKpHg-1 X-Mimecast-MFC-AGG-ID: sGEgBa_8OoaA5EI8toKpHg_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 06/12] docs/qapi-domain: add qapi:namespace directive Date: Fri, 14 Mar 2025 11:10:32 +0100 Message-ID: <20250314101038.2408751-7-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.17 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947149917019000 Content-Type: text/plain; charset="utf-8" From: John Snow Add a new directive that marks the beginning of a QAPI "namespace", for example; "QMP", "QGA" or "QSD". This directive will associate all subsequent QAPI directives in a document with the specified namespace. This does not change the visual display of any of the definitions or index entries, but does change the "Fully Qualified Name" inside the QAPI domain's object table. This allows for two different "namespaces" to define entities with otherwise identical names -- which will come in handy for documenting both QEMU QMP and the QEMU Storage Daemon. Signed-off-by: John Snow Message-ID: <20250313044312.189276-6-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 20 +++++++++++++++++++- docs/sphinx/qapi_domain.py | 13 +++++++++++++ 2 files changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 51b283277e..73e13ab45c 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -464,7 +464,8 @@ removed in a future version. QAPI standard options --------------------- =20 -All QAPI directives -- *except* for module -- support these common options. +All QAPI directives -- *except* for namespace and module -- support +these common options. =20 * ``:namespace: name`` -- This option allows you to override the namespace association of a given definition. @@ -482,6 +483,23 @@ All QAPI directives -- *except* for module -- support = these common options. production code. =20 =20 +qapi:namespace +-------------- + +The ``qapi:namespace`` directive marks the start of a QAPI namespace. It +does not take a content body, nor any options. All subsequent QAPI +directives are associated with the most recent namespace. This affects +the definition's "fully qualified name", allowing two different +namespaces to create an otherwise identically named definition. + +Example:: + + .. qapi:namespace:: QMP + + +This directive has no visible effect. + + qapi:module ----------- =20 diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 6485c43206..a204af9b06 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -38,6 +38,7 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging +from sphinx.util.docutils import SphinxDirective from sphinx.util.nodes import make_id, make_refnode =20 =20 @@ -645,6 +646,17 @@ def run(self) -> List[Node]: return ret =20 =20 +class QAPINamespace(SphinxDirective): + has_content =3D False + required_arguments =3D 1 + + def run(self) -> List[Node]: + namespace =3D self.arguments[0].strip() + self.env.ref_context["qapi:namespace"] =3D namespace + + return [] + + class QAPIIndex(Index): """ Index subclass to provide the QAPI definition index. @@ -726,6 +738,7 @@ class QAPIDomain(Domain): # Each of these provides a rST directive, # e.g. .. qapi:module:: block-core directives =3D { + "namespace": QAPINamespace, "module": QAPIModule, "command": QAPICommand, "event": QAPIEvent, --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947206; cv=none; d=zohomail.com; s=zohoarc; b=cGM3xwHk0aKYtRi/BQF/AyorGzoO41EzfrsxzdJNmMn9r1/J5+g/i1z+aoSxTGweV+Zww0GLlNwyKMqUD5sb1CTFvFeFVmQwY3lJjy9eFvAUWIhB5VIEOs9A9phb4TrX9qvYfQYhUem4XHDpaTgirGzXGz79oUIrLOlfT7QP5w0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947206; 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=baQ+HaROmmAM+TkdGfumBlYGTIxDaOf3UHesS9VAqik=; b=VnGegK1rYovpGN3TNf+U/IyPXsBnU44aJmlDVS0jlsdY1/+vcZUOGhPLwF4JHDgF6yzNS8PcYL4+mS1UXSS54qIS/zK8LLXLSj50n2qVPEXic7rKeddaQCZ+57qzGoU2aU6ubjqVOUBVA+dExXUIkMy41REqP6kDGLFAaxhIb78= 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 1741947206835393.3901690651469; Fri, 14 Mar 2025 03:13:26 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20M-0006Ke-RC; Fri, 14 Mar 2025 06:11:02 -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 1tt20F-0006Iq-11 for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -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 1tt20C-00023C-Mn for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -0400 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-641-RBZoqkw3Ol2flFrXXwJXQA-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.111]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E27571956048 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 5F8A41801756 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D28AD21E65FF; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=baQ+HaROmmAM+TkdGfumBlYGTIxDaOf3UHesS9VAqik=; b=S+mFu/zaqGtB9kcfe2HWoJVAj65fIdIekYhLUsZEox1+GtLLS8yLCEfawELnEUmQgfFA2A wt9x+DJKocWocUFgiiO3BD5e0mOlSfuDPlOmJCum3FweV6Kg7gUiskaZAhU4bCamQFqiY5 IKDrei8sL9UJ+FqoHttGOeWFkI2sSlo= X-MC-Unique: RBZoqkw3Ol2flFrXXwJXQA-1 X-Mimecast-MFC-AGG-ID: RBZoqkw3Ol2flFrXXwJXQA_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 07/12] docs/qapidoc: add :namespace: option to qapi-doc directive Date: Fri, 14 Mar 2025 11:10:33 +0100 Message-ID: <20250314101038.2408751-8-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.111 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947208259019000 Content-Type: text/plain; charset="utf-8" From: John Snow Add a :namespace: option to the qapi-doc directive, which inserts a qapi:namespace directive into the start of the generated document. This, in turn, associates all auto-generated definitions by this directive with the specified namespace. The source info for these generated lines are credited to the start of the qapi-doc directive, which isn't precisely correct, but I wasn't sure how to get it more accurate without some re-parsing shenanigans. Signed-off-by: John Snow Message-ID: <20250313044312.189276-7-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapidoc.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 432fef04b0..661b2c4ed0 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -451,6 +451,12 @@ def visit_entity(self, ent: QAPISchemaDefinition) -> N= one: finally: self._curr_ent =3D None =20 + def set_namespace(self, namespace: str, source: str, lineno: int) -> N= one: + self.add_line_raw( + f".. qapi:namespace:: {namespace}", source, lineno + 1 + ) + self.ensure_blank_line() + =20 class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module @@ -496,6 +502,7 @@ class QAPIDocDirective(NestedDirective): optional_arguments =3D 1 option_spec =3D { "qapifile": directives.unchanged_required, + "namespace": directives.unchanged, "transmogrify": directives.flag, } has_content =3D False @@ -510,6 +517,11 @@ def transmogrify(self, schema: QAPISchema) -> nodes.El= ement: vis =3D Transmogrifier() modules =3D set() =20 + if "namespace" in self.options: + vis.set_namespace( + self.options["namespace"], *self.get_source_info() + ) + for doc in schema.docs: module_source =3D doc.info.fname if module_source not in modules: --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947120; cv=none; d=zohomail.com; s=zohoarc; b=DsqUivw9briDM18cvBrh/HWisyztB6Jwqw6N/xySbh71Jz8G2++0+Y3r11l6IHTAtH4MVcOFYa2Hlj20su/kxoayRibza+R2H2qpOj7Th/746NnB9b5uO0jeXG/GsT3fnXmeuusg/p+xUDoDrw6STKBZ3M57gtYF3FOaqSYq+RU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947120; 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=9uQzNm9rtPGNSZZCL68DEDr5gPnofc1S6ofrtgVHx3g=; b=ijtLQ9hCcTsX6BrPfklmC+XOuTwJ57se9BUM0o7sF8XEhWslmQLl03CEPES7Qg/FWUFb7BpjiHRHaqgUoJ4C0JGYjP3yYF0WP/EmfTEtfpYrDhafT3DhHhKDyrsXiw7/VFOwiL13HQlpxAiD0AwzJcDTzX8lGBB95c3n87Fxp4M= 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 1741947120410242.15571539651273; Fri, 14 Mar 2025 03:12:00 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20N-0006LT-Ox; Fri, 14 Mar 2025 06:11:03 -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 1tt20F-0006Is-78 for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -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 1tt20C-000231-Di for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-657-c_7pYkZ_PgqH_sZp8ihKUA-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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 35EA7180AB1C for ; Fri, 14 Mar 2025 10:10:49 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8B7931954B32 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id D68FE21E6560; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=9uQzNm9rtPGNSZZCL68DEDr5gPnofc1S6ofrtgVHx3g=; b=OQhW1iHnNaQW7eAlseRtNW3o1/EK9SNBkUP0BfgW9c/SDyAn88tiQx2TAth8lBFTUgRUt3 47upQb6gM5wSjdmKYO5XuqFCaVYvQOmrlRgvXfrIyWabvWH7xwJ/kyyjFIeE3VR9POOszN f/Ne9ownjLI0lkAIRVAbVYrLfSnc3vc= X-MC-Unique: c_7pYkZ_PgqH_sZp8ihKUA-1 X-Mimecast-MFC-AGG-ID: c_7pYkZ_PgqH_sZp8ihKUA_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 08/12] docs/qapi_domain: add namespace support to cross-references Date: Fri, 14 Mar 2025 11:10:34 +0100 Message-ID: <20250314101038.2408751-9-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 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=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947121942019000 Content-Type: text/plain; charset="utf-8" From: John Snow This patch does three things: 1. Record the current namespace context in pending_xrefs so it can be used for link resolution later, 2. Pass that recorded namespace context to find_obj() when resolving a reference, and 3. Wildly and completely rewrite find_obj(). cross-reference support is expanded to tolerate the presence or absence of either namespace or module, and to cope with the presence or absence of contextual information for either. References now work like this: 1. If the explicit reference target is recorded in the domain's object registry, we link to that target and stop looking. We do this lookup regardless of how fully qualified the target is, which allows direct references to modules (which don't have a module component to their names) or direct references to definitions that may or may not belong to a namespace or module. 2. If contextual information is available from qapi:namespace or qapi:module directives, try using those components to find a direct match to the implied target name. 3. If both prior lookups fail, generate a series of regular expressions looking for wildcard matches in order from most to least specific. Any explicitly provided components (namespace, module) *must* match exactly, but both contextual and entirely omitted components are allowed to differ from the search result. Note that if more than one result is found, Sphinx will emit a warning (a build error for QEMU) and list all of the candidate references. The practical upshot is that in the large majority of cases, namespace and module information is not required when creating simple `references` to definitions from within the same context -- even when identical definitions exist in other contexts. Even when using simple `references` from elsewhere in the QEMU documentation manual, explicit namespace info is not required if there is only one definition by that name. Disambiguation *will* be required from outside of the QAPI documentation when referencing e.g. block-core definitions, which are shared between QEMU QMP and the QEMU Storage Daemon. In that case, there are two options: A: References can be made partially or fully explicit, e.g. `QMP:block-dirty-bitmap-add` will link to the QEMU version of the definition, while `QSD:block-dirty-bitmap-add` would link to the QSD version. B: If all of the references in a document are intended to go to the same place, you can insert a "qapi:namespace:: QMP" directive to influence the fuzzy-searching for later references. Signed-off-by: John Snow Message-ID: <20250313044312.189276-8-jsnow@redhat.com> Acked-by: Markus Armbruster [Commit message typo fixed] Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 34 ++++++++-- docs/sphinx/qapi_domain.py | 127 ++++++++++++++++++++++++------------- 2 files changed, 114 insertions(+), 47 deletions(-) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 73e13ab45c..4705ba255e 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -400,11 +400,10 @@ Namespaces Mimicking the `Python domain target specification syntax `_, QAPI allows you to specify the fully qualified path for a data -type. QAPI enforces globally unique names, so it's unlikely you'll need -this specific feature, but it may be extended in the near future to -allow referencing identically named commands and data types from -different utilities; i.e. QEMU Storage Daemon vs QMP. +type. =20 +* A namespace can be explicitly provided; + e.g. ``:qapi:type:`QMP:BitmapSyncMode`` * A module can be explicitly provided; ``:qapi:type:`block-core.BitmapSyncMode``` will render to: :qapi:type:`block-core.BitmapSyncMode` @@ -413,6 +412,28 @@ different utilities; i.e. QEMU Storage Daemon vs QMP. will render to: :qapi:type:`~block-core.BitmapSyncMode` =20 =20 +Target resolution +----------------- + +Any cross-reference to a QAPI type, whether using the ```any``` style of +reference or the more explicit ```:qapi:any:`target``` syntax, allows +for the presence or absence of either the namespace or module +information. + +When absent, their value will be inferred from context by the presence +of any ``qapi:namespace`` or ``qapi:module`` directives preceding the +cross-reference. + +If no results are found when using the inferred values, other +namespaces/modules will be searched as a last resort; but any explicitly +provided values must always match in order to succeed. + +This allows for efficient cross-referencing with a minimum of syntax in +the large majority of cases, but additional context or namespace markup +may be required outside of the QAPI reference documents when linking to +items that share a name across multiple documented QAPI schema. + + Custom link text ---------------- =20 @@ -492,6 +513,11 @@ directives are associated with the most recent namespa= ce. This affects the definition's "fully qualified name", allowing two different namespaces to create an otherwise identically named definition. =20 +This directive also influences how reference resolution works for any +references that do not explicity specify a namespace, so this directive +can be used to nudge references into preferring targets from within that +namespace. + Example:: =20 .. qapi:namespace:: QMP diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index a204af9b06..a8a85a2de3 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -7,6 +7,7 @@ =20 from __future__ import annotations =20 +import re from typing import ( TYPE_CHECKING, List, @@ -94,6 +95,7 @@ def process_link( title: str, target: str, ) -> tuple[str, str]: + refnode["qapi:namespace"] =3D env.ref_context.get("qapi:namespace") refnode["qapi:module"] =3D env.ref_context.get("qapi:module") =20 # Cross-references that begin with a tilde adjust the title to @@ -830,40 +832,44 @@ def merge_domaindata( self.objects[fullname] =3D obj =20 def find_obj( - self, modname: str, name: str, typ: Optional[str] - ) -> list[tuple[str, ObjectEntry]]: + self, namespace: str, modname: str, name: str, typ: Optional[str] + ) -> List[Tuple[str, ObjectEntry]]: """ - Find a QAPI object for "name", perhaps using the given module. + Find a QAPI object for "name", maybe using contextual information. =20 Returns a list of (name, object entry) tuples. =20 - :param modname: The current module context (if any!) - under which we are searching. - :param name: The name of the x-ref to resolve; - may or may not include a leading module. - :param type: The role name of the x-ref we're resolving, if provid= ed. - (This is absent for "any" lookups.) + :param namespace: The current namespace context (if any!) under + which we are searching. + :param modname: The current module context (if any!) under + which we are searching. + :param name: The name of the x-ref to resolve; may or may not + include leading context. + :param type: The role name of the x-ref we're resolving, if + provided. This is absent for "any" role lookups. """ if not name: return [] =20 - names: list[str] =3D [] - matches: list[tuple[str, ObjectEntry]] =3D [] + # ## + # what to search for + # ## =20 - fullname =3D name - if "." in fullname: - # We're searching for a fully qualified reference; - # ignore the contextual module. - pass - elif modname: - # We're searching for something from somewhere; - # try searching the current module first. - # e.g. :qapi:cmd:`query-block` or `query-block` is being searc= hed. - fullname =3D f"{modname}.{name}" + parts =3D list(QAPIDescription.split_fqn(name)) + explicit =3D tuple(bool(x) for x in parts) + + # Fill in the blanks where possible: + if namespace and not parts[0]: + parts[0] =3D namespace + if modname and not parts[1]: + parts[1] =3D modname + + implicit_fqn =3D "" + if all(parts): + implicit_fqn =3D f"{parts[0]}:{parts[1]}.{parts[2]}" =20 if typ is None: - # type isn't specified, this is a generic xref. - # search *all* qapi-specific object types. + # :any: lookup, search everything: objtypes: List[str] =3D list(self.object_types) else: # type is specified and will be a role (e.g. obj, mod, cmd) @@ -871,25 +877,57 @@ def find_obj( # using the QAPIDomain.object_types table. objtypes =3D self.objtypes_for_role(typ, []) =20 - if name in self.objects and self.objects[name].objtype in objtypes: - names =3D [name] - elif ( - fullname in self.objects - and self.objects[fullname].objtype in objtypes - ): - names =3D [fullname] - else: - # exact match wasn't found; e.g. we are searching for - # `query-block` from a different (or no) module. - searchname =3D "." + name - names =3D [ - oname - for oname in self.objects - if oname.endswith(searchname) - and self.objects[oname].objtype in objtypes - ] + # ## + # search! + # ## =20 - matches =3D [(oname, self.objects[oname]) for oname in names] + def _search(needle: str) -> List[str]: + if ( + needle + and needle in self.objects + and self.objects[needle].objtype in objtypes + ): + return [needle] + return [] + + if found :=3D _search(name): + # Exact match! + pass + elif found :=3D _search(implicit_fqn): + # Exact match using contextual information to fill in the gaps. + pass + else: + # No exact hits, perform applicable fuzzy searches. + searches =3D [] + + esc =3D tuple(re.escape(s) for s in parts) + + # Try searching for ns:*.name or ns:name + if explicit[0] and not explicit[1]: + searches.append(f"^{esc[0]}:([^\\.]+\\.)?{esc[2]}$") + # Try searching for *:module.name or module.name + if explicit[1] and not explicit[0]: + searches.append(f"(^|:){esc[1]}\\.{esc[2]}$") + # Try searching for context-ns:*.name or context-ns:name + if parts[0] and not (explicit[0] or explicit[1]): + searches.append(f"^{esc[0]}:([^\\.]+\\.)?{esc[2]}$") + # Try searching for *:context-mod.name or context-mod.name + if parts[1] and not (explicit[0] or explicit[1]): + searches.append(f"(^|:){esc[1]}\\.{esc[2]}$") + # Try searching for *:name, *.name, or name + if not (explicit[0] or explicit[1]): + searches.append(f"(^|:|\\.){esc[2]}$") + + for search in searches: + if found :=3D [ + oname + for oname in self.objects + if re.search(search, oname) + and self.objects[oname].objtype in objtypes + ]: + break + + matches =3D [(oname, self.objects[oname]) for oname in found] if len(matches) > 1: matches =3D [m for m in matches if not m[1].aliased] return matches @@ -904,8 +942,9 @@ def resolve_xref( node: pending_xref, contnode: Element, ) -> nodes.reference | None: + namespace =3D node.get("qapi:namespace") modname =3D node.get("qapi:module") - matches =3D self.find_obj(modname, target, typ) + matches =3D self.find_obj(namespace, modname, target, typ) =20 if not matches: # Normally, we could pass warn_dangling=3DTrue to QAPIXRefRole= (), @@ -958,7 +997,9 @@ def resolve_any_xref( contnode: Element, ) -> List[Tuple[str, nodes.reference]]: results: List[Tuple[str, nodes.reference]] =3D [] - matches =3D self.find_obj(node.get("qapi:module"), target, None) + matches =3D self.find_obj( + node.get("qapi:namespace"), node.get("qapi:module"), target, N= one + ) for name, obj in matches: rolename =3D self.role_for_objtype(obj.objtype) assert rolename is not None --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947140; cv=none; d=zohomail.com; s=zohoarc; b=A0ICsXMREyitaGfF78OxpoOCQQqfVpIeQVVs053v/UXsuuL2V7pnCqHTEsoNK+WggimDhJftHE07ZnWWiJ3aYalCG3h+vvL12hY7u0/QzpJxi71+idozo9c2Y8cx0uP0XJlQyf1GspdOAV3ZIIcNStBCCbRBQ3Z/Kp9UmgcI1NY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947140; 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=8jBRtbQj34+6ynEpVBu15Qf4PyPm1m8GNkAPco2/M1E=; b=B3SieSD7ofW9E/1zvlj6M8JopYDL/tUoRs2b3Fkgt+NMgEYcRfr24n6iBiuHCVxHz+KLQeN09kWle32XTd0woRqdNavDa5CKI2jCR3rutRKc30PS3EyzIJ7St84/1q7D7RD+NGMATQSgjQ3P0sOTAKBHKrgIqbMUX9gI4XUJe4U= 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 1741947140746566.1022220532701; Fri, 14 Mar 2025 03:12:20 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20N-0006LR-O0; Fri, 14 Mar 2025 06:11:03 -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 1tt20G-0006JC-G5 for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:58 -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 1tt20C-00023M-SU for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -0400 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-483-CT8lFtk_M4OMcqbnINKjxA-1; Fri, 14 Mar 2025 06:10:50 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 916EC1955D82 for ; Fri, 14 Mar 2025 10:10:49 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B1B561828AA8 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DA67721E6561; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=8jBRtbQj34+6ynEpVBu15Qf4PyPm1m8GNkAPco2/M1E=; b=JNpHqr/q1VwcabkpCmghRbHEUDQUBSvRml4lrIld5I5TlnsIoyMpEld70oZJa2HszKrXiV BJOvhZNVi2rueJTf70OEo4OJLSUmQud/IRFzcFNmwu5B56OhXhLZtAW1h0MeTnB6OdGiEs wV4aiMV3Gq9uSkfzgZsjMkPihZAT4Ak= X-MC-Unique: CT8lFtk_M4OMcqbnINKjxA-1 X-Mimecast-MFC-AGG-ID: CT8lFtk_M4OMcqbnINKjxA_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 09/12] docs/qapi-domain: add namespaced index support Date: Fri, 14 Mar 2025 11:10:35 +0100 Message-ID: <20250314101038.2408751-10-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947143891019100 Content-Type: text/plain; charset="utf-8" From: John Snow Generate an index-per-namespace for the QAPI domain. Due to a limitation with Sphinx's architecture, these indices must be defined during setup time and cannot be dynamically created on-demand when a namespace directive is encountered. Owing to that limitation, add a configuration value to conf.py that specifies which QAPI namespaces we'll generate indices for. Indices will be named after their namespace, e.g. the "QMP" namespace will generate to "qapi-qmp-index.html" and can be referenced using `qapi-qmp-index`. Signed-off-by: John Snow Message-ID: <20250313044312.189276-9-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 3 +++ docs/sphinx/qapi_domain.py | 51 +++++++++++++++++++++++++++----------- 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index a3f9fa63d9..175491148c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -161,6 +161,9 @@ "see also", } =20 +# Due to a limitation in Sphinx, we need to know which indices to +# generate in advance. Adding a namespace here allows that generation. +qapi_namespaces =3D set() =20 # -- Options for HTML output ---------------------------------------------- =20 diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index a8a85a2de3..c94af5719c 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -8,11 +8,13 @@ from __future__ import annotations =20 import re +import types from typing import ( TYPE_CHECKING, List, NamedTuple, Tuple, + Type, cast, ) =20 @@ -669,6 +671,7 @@ class QAPIIndex(Index): name =3D "index" localname =3D _("QAPI Index") shortname =3D _("QAPI Index") + namespace =3D "" =20 def generate( self, @@ -678,25 +681,20 @@ def generate( content: Dict[str, List[IndexEntry]] =3D {} collapse =3D False =20 - # list of all object (name, ObjectEntry) pairs, sorted by name - # (ignoring the module) - objects =3D sorted( - self.domain.objects.items(), - key=3Dlambda x: x[0].split(".")[-1].lower(), - ) - - for objname, obj in objects: + for objname, obj in self.domain.objects.items(): if docnames and obj.docname not in docnames: continue =20 - # Strip the module name out: - objname =3D objname.split(".")[-1] + ns, _mod, name =3D QAPIDescription.split_fqn(objname) + + if self.namespace !=3D ns: + continue =20 # Add an alphabetical entry: - entries =3D content.setdefault(objname[0].upper(), []) + entries =3D content.setdefault(name[0].upper(), []) entries.append( IndexEntry( - objname, 0, obj.docname, obj.node_id, obj.objtype, "",= "" + name, 0, obj.docname, obj.node_id, obj.objtype, "", "" ) ) =20 @@ -704,10 +702,14 @@ def generate( category =3D obj.objtype.title() + "s" entries =3D content.setdefault(category, []) entries.append( - IndexEntry(objname, 0, obj.docname, obj.node_id, "", "", "= ") + IndexEntry(name, 0, obj.docname, obj.node_id, "", "", "") ) =20 - # alphabetically sort categories; type names first, ABC entries la= st. + # Sort entries within each category alphabetically + for category in content: + content[category] =3D sorted(content[category]) + + # Sort the categories themselves; type names first, ABC entries la= st. sorted_content =3D sorted( content.items(), key=3Dlambda x: (len(x[0]) =3D=3D 1, x[0]), @@ -780,6 +782,21 @@ def objects(self) -> Dict[str, ObjectEntry]: ret =3D self.data.setdefault("objects", {}) return ret # type: ignore[no-any-return] =20 + def setup(self) -> None: + namespaces =3D set(self.env.app.config.qapi_namespaces) + for namespace in namespaces: + new_index: Type[QAPIIndex] =3D types.new_class( + f"{namespace}Index", bases=3D(QAPIIndex,) + ) + new_index.name =3D f"{namespace.lower()}-index" + new_index.localname =3D _(f"{namespace} Index") + new_index.shortname =3D _(f"{namespace} Index") + new_index.namespace =3D namespace + + self.indices.append(new_index) + + super().setup() + def note_object( self, name: str, @@ -1019,6 +1036,12 @@ def setup(app: Sphinx) -> Dict[str, Any]: "env", # Setting impacts parsing phase types=3Dset, ) + app.add_config_value( + "qapi_namespaces", + set(), + "env", + types=3Dset, + ) app.add_domain(QAPIDomain) =20 return { --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947141; cv=none; d=zohomail.com; s=zohoarc; b=BZMX9r0TSVgUdVn9Q903S0KzwW4CN/TicDrO1gLBeww5X0Uh7jJ7vQJyJaOPHBn7XKlBZjHhWNpKPE0CvZXThuv+aYpR2iG8m4OxFc2EfLgUgUZGLhsZvN4NtGTLPSQNYq1AuAzzVOjNvVoC9e3mNL922oW9CY6Xj2YX7vcdjAY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947141; 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=eHOavQHaN85j3yGCJ/6p70cICn1vQD2MyMqNz9D7VpQ=; b=N9pkmjSXTxlY0TDuihNooR8ISwoG8zHooCuJS1VBBMOlbpkgAYX3aXzulMHnwEYn/qUAQPZ6GMRtwN8JLnU5A4JwmAgLKfaOFWEs6F57OQO/gwHwaeKDZrnDYWcWae12WSYcW8sF76XX7T8Ccv7hyGzT751vQBpbKrKjFxt30Po= 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 1741947141591935.869289291397; Fri, 14 Mar 2025 03:12:21 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20O-0006MG-Nx; Fri, 14 Mar 2025 06:11:04 -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 1tt20G-0006JK-Gs for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:58 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tt20C-00022t-TX for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -0400 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-572-BRv48f8pObWT4GWV3iuflQ-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E8E531955DDE for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 8A9DC1828AA7 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id DE1BF21E6562; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=eHOavQHaN85j3yGCJ/6p70cICn1vQD2MyMqNz9D7VpQ=; b=Z8Tu54CJVUkE4oTItB3WfjDCSryQ2nht62Y5XwVw8hatkg5WrIfEkYl6wBlKSQM9YPaCbB j0+VA+PWRSO7HYpN27WIlRZdllJxuEfB7kaOcF5N84V6lyACoK7HTaIsS73Vh+EF7IugzC B0yOfT9AcZemA4Q1OHOI5eFgfK77P/w= X-MC-Unique: BRv48f8pObWT4GWV3iuflQ-1 X-Mimecast-MFC-AGG-ID: BRv48f8pObWT4GWV3iuflQ_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 10/12] docs: add QAPI namespace "QMP" to qemu-qmp-ref Date: Fri, 14 Mar 2025 11:10:36 +0100 Message-ID: <20250314101038.2408751-11-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.133.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947143770019100 Content-Type: text/plain; charset="utf-8" From: John Snow This also creates the qapi-qmp-index.html index and cross-reference target. Signed-off-by: John Snow Message-ID: <20250313044312.189276-10-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 4 +++- docs/interop/qemu-qmp-ref.rst | 1 + qapi/qapi-schema.json | 2 +- 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 175491148c..9a86e84a80 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -163,7 +163,9 @@ =20 # Due to a limitation in Sphinx, we need to know which indices to # generate in advance. Adding a namespace here allows that generation. -qapi_namespaces =3D set() +qapi_namespaces =3D { + "QMP", +} =20 # -- Options for HTML output ---------------------------------------------- =20 diff --git a/docs/interop/qemu-qmp-ref.rst b/docs/interop/qemu-qmp-ref.rst index e95eeac45e..ef8792b53f 100644 --- a/docs/interop/qemu-qmp-ref.rst +++ b/docs/interop/qemu-qmp-ref.rst @@ -8,3 +8,4 @@ QEMU QMP Reference Manual =20 .. qapi-doc:: qapi/qapi-schema.json :transmogrify: + :namespace: QMP diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index 4475e81cc3..c41c01eb2a 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -5,7 +5,7 @@ # # This document describes all commands currently supported by QMP. # -# For locating a particular item, please see the `qapi-index`. +# For locating a particular item, please see the `qapi-qmp-index`. # # Most of the time their usage is exactly the same as in the user # Monitor, this means that any other document which also describe --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947188; cv=none; d=zohomail.com; s=zohoarc; b=JhxJ8AT1z3+kJpTjkNcj+2MEQ91jJvfAUx+6iXICWHNplLrhLPIA6dXVTr/vYrolGAUKkaq2/VIacLHJeJKoGO2PokKhIlFPRrPAydA+8871Ih2C5w2QhlH28XbyCutME69IEDff1IfiNXh8T9N9yi88icYQOE7dyhiu++Fb4U0= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947188; 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=nAOwRfEQX1fMHZemJle1vc9sdr0bBc0WMo88DueGw5U=; b=SWyNg9TUkXz9Ha2kLYs8R6OYJ5fIiECYsQljrp+IPEwUmOOTLOafJFoqy0E/jhjjetpugFK7hYBKxU5vvGD7dlBLAl5qJbhnEpRLZXQjZMzFUVlmobmt+5r36UaINTUUm/O4Ujtu6fei+IKG6KggqZg3DGzsUJmNphZwQAIWYy8= 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 1741947188763700.4011325548025; Fri, 14 Mar 2025 03:13:08 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20O-0006MX-Rj; Fri, 14 Mar 2025 06:11:04 -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 1tt20F-0006Ir-2L for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -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 1tt20C-00023D-Nh for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -0400 Received: from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-641-A8X5GfHJPxSoD16vSa5bqw-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id B7669180AF50 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 367C21828A93 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E3CC721E64C0; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=nAOwRfEQX1fMHZemJle1vc9sdr0bBc0WMo88DueGw5U=; b=GzkCqZ5ZXFEpO+Zsw4pRwxbA+JvyDRC125ClW9eP5ckY9XY6PQHAFmpys2fu9kN3UQxvlR AeRL513gI7Dape4oTksgJ+zk5ZGt5g4/6tU70eNoSX4a1DCz6m4XVrnyYvxxL5RszaM1iw fcuOt3VkcT35/XMHyNS34Wfbsopr7ro= X-MC-Unique: A8X5GfHJPxSoD16vSa5bqw-1 X-Mimecast-MFC-AGG-ID: A8X5GfHJPxSoD16vSa5bqw_1741947048 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 11/12] docs: disambiguate references in qapi-domain.rst Date: Fri, 14 Mar 2025 11:10:37 +0100 Message-ID: <20250314101038.2408751-12-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947189991019000 Content-Type: text/plain; charset="utf-8" From: John Snow Before we enable the QGA and QSD namespaces, we need to disambiguate some of the references that would become ambiguous as a result! Signed-off-by: John Snow Message-ID: <20250313044312.189276-11-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/devel/qapi-domain.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/devel/qapi-domain.rst b/docs/devel/qapi-domain.rst index 4705ba255e..a748529f51 100644 --- a/docs/devel/qapi-domain.rst +++ b/docs/devel/qapi-domain.rst @@ -385,13 +385,13 @@ Type names in references can be surrounded by bracket= s, like ``[typename]``, to indicate an array of that type. The cross-reference will apply only to the type name between the brackets. For example; ``:qapi:type:`[Qcow2BitmapInfoFlags]``` renders to: -:qapi:type:`[Qcow2BitmapInfoFlags]` +:qapi:type:`[QMP:Qcow2BitmapInfoFlags]` =20 To indicate an optional argument/member in a field list, the type name can be suffixed with ``?``. The cross-reference will be transformed to "type, Optional" with the link applying only to the type name. For example; ``:qapi:type:`BitmapSyncMode?``` renders to: -:qapi:type:`BitmapSyncMode?` +:qapi:type:`QMP:BitmapSyncMode?` =20 =20 Namespaces @@ -405,11 +405,11 @@ type. * A namespace can be explicitly provided; e.g. ``:qapi:type:`QMP:BitmapSyncMode`` * A module can be explicitly provided; - ``:qapi:type:`block-core.BitmapSyncMode``` will render to: - :qapi:type:`block-core.BitmapSyncMode` + ``:qapi:type:`QMP:block-core.BitmapSyncMode``` will render to: + :qapi:type:`QMP:block-core.BitmapSyncMode` * If you don't want to display the "fully qualified" name, it can be - prefixed with a tilde; ``:qapi:type:`~block-core.BitmapSyncMode``` - will render to: :qapi:type:`~block-core.BitmapSyncMode` + prefixed with a tilde; ``:qapi:type:`~QMP:block-core.BitmapSyncMode``` + will render to: :qapi:type:`~QMP:block-core.BitmapSyncMode` =20 =20 Target resolution @@ -444,7 +444,7 @@ using the ``custom text `` syntax. =20 For example, ``:qapi:cmd:`Merge dirty bitmaps ``` will render as: :qapi:cmd:`Merge dirty -bitmaps ` +bitmaps ` =20 =20 Directives --=20 2.48.1 From nobody Fri Apr 4 03:33:00 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=1741947212; cv=none; d=zohomail.com; s=zohoarc; b=kiDbA3BFHt0cMCY/q/R0Ll40wIaDk7uc8wW9wAIpTRVoh12O2xsg5NNRCDjxwL0xsMK95FtbHDp9G6dPgAaMjQjKgiGVDn/TH6yLe/rzgsl/XkMReruQq1bRaPzQWpmz8KvS6y/tgTFW+GjFGEmyp4XdEF7Za79IQBzA+rI5+O8= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741947212; 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=FMhx6loXPBAjuIXAlLsHOTwdp7+0R4NgyYOtMoaW8X0=; b=XV3/Rk9iUDQ7DiT7aOUEnPkkE9ci2nsuMKVCcAGq3Vs9T+EDWluVc4kTRSfNvc1qm/KoR/2XpOLAK5HaaBulfFUsL/8FN842+3PPgEJPIIx65Q9CY/4fgXI/rt9l/mykTc5BD397/8ykT2w/WULK8Hvo2WndRJIWqNYCYW1nk/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 17419472122402.8861979645438396; Fri, 14 Mar 2025 03:13:32 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tt20M-0006KS-1F; Fri, 14 Mar 2025 06:11:02 -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 1tt20E-0006Ip-Se for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:56 -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 1tt20C-00023B-ML for qemu-devel@nongnu.org; Fri, 14 Mar 2025 06:10:54 -0400 Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-641-9AGI9JAvMsGXl2srunHEQA-1; Fri, 14 Mar 2025 06:10:49 -0400 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id E21881800258 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 88CCF1828AA4 for ; Fri, 14 Mar 2025 10:10:48 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id E652121E64F2; Fri, 14 Mar 2025 11:10:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741947051; 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=FMhx6loXPBAjuIXAlLsHOTwdp7+0R4NgyYOtMoaW8X0=; b=Rr2AcfnptxhEdZp48VNPQOK5b/urYpTK8Vmsps5oFYErUh2d2HgGubaXgj/HvNljg939l9 XuGlVvvBYACM6Jgkl9C/a5i4oWZS/xbpI34o5NZWlGt16wwJNiOIPTRu2qvWKxuH+l7LBB SdVPHb9jXxl265V2o6kAvBr7liuDZa4= X-MC-Unique: 9AGI9JAvMsGXl2srunHEQA-1 X-Mimecast-MFC-AGG-ID: 9AGI9JAvMsGXl2srunHEQA_1741947049 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 12/12] docs: enable transmogrifier for QSD and QGA Date: Fri, 14 Mar 2025 11:10:38 +0100 Message-ID: <20250314101038.2408751-13-armbru@redhat.com> In-Reply-To: <20250314101038.2408751-1-armbru@redhat.com> References: <20250314101038.2408751-1-armbru@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Received-SPF: pass client-ip=170.10.129.124; envelope-from=armbru@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_VALIDITY_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741947213895019100 Content-Type: text/plain; charset="utf-8" From: John Snow This also creates the `qapi-qsd-index` and `qapi-qga-index` QMP indices. Signed-off-by: John Snow Message-ID: <20250313044312.189276-12-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/conf.py | 2 ++ docs/interop/qemu-ga-ref.rst | 2 ++ docs/interop/qemu-storage-daemon-qmp-ref.rst | 2 ++ qga/qapi-schema.json | 3 +++ storage-daemon/qapi/qapi-schema.json | 8 ++++++++ 5 files changed, 17 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 9a86e84a80..7b5712e122 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -164,7 +164,9 @@ # Due to a limitation in Sphinx, we need to know which indices to # generate in advance. Adding a namespace here allows that generation. qapi_namespaces =3D { + "QGA", "QMP", + "QSD", } =20 # -- Options for HTML output ---------------------------------------------- diff --git a/docs/interop/qemu-ga-ref.rst b/docs/interop/qemu-ga-ref.rst index 032d492455..19b5c7a549 100644 --- a/docs/interop/qemu-ga-ref.rst +++ b/docs/interop/qemu-ga-ref.rst @@ -5,3 +5,5 @@ QEMU Guest Agent Protocol Reference :depth: 3 =20 .. qapi-doc:: qga/qapi-schema.json + :transmogrify: + :namespace: QGA diff --git a/docs/interop/qemu-storage-daemon-qmp-ref.rst b/docs/interop/qe= mu-storage-daemon-qmp-ref.rst index 9fed68152f..d0228d63b8 100644 --- a/docs/interop/qemu-storage-daemon-qmp-ref.rst +++ b/docs/interop/qemu-storage-daemon-qmp-ref.rst @@ -5,3 +5,5 @@ QEMU Storage Daemon QMP Reference Manual :depth: 3 =20 .. qapi-doc:: storage-daemon/qapi/qapi-schema.json + :transmogrify: + :namespace: QSD diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 995594aaf4..35ec0e7db3 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -3,6 +3,9 @@ =20 ## # =3D QEMU guest agent protocol commands and structs +# +# For a concise listing of all commands, events, and types in the QEMU +# guest agent, please consult the `qapi-qga-index`. ## =20 { 'pragma': { 'doc-required': true } } diff --git a/storage-daemon/qapi/qapi-schema.json b/storage-daemon/qapi/qap= i-schema.json index f10c949490..2a562ee32e 100644 --- a/storage-daemon/qapi/qapi-schema.json +++ b/storage-daemon/qapi/qapi-schema.json @@ -13,6 +13,14 @@ # the array type in the main schema, even if it is unused outside of the # storage daemon. =20 +## +# =3D QEMU storage daemon protocol commands and structs +# +# For a concise listing of all commands, events, and types in the QEMU +# storage daemon, please consult the `qapi-qsd-index`. +## + + { 'include': '../../qapi/pragma.json' } =20 # Documentation generated with qapi-gen.py is in source order, with --=20 2.48.1