From nobody Fri Apr 4 03:46:02 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=1741696967; cv=none; d=zohomail.com; s=zohoarc; b=Nh8TxbS/4UND81G8CLaGd40gLQcDvuIz+Q1stDIJCKHs5r1FgYH66DEPBqXxTahPeoCrdz+iLIiTi6oPyajasP9/TvUr6kinp35EJU8Xg2oVmU60sz4nh3qo+FORqDC+uwMfCj7gpgMEnitnsn0Zf9jrx0QOfU6NE0cqpLTG8OY= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741696967; 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=d7vRvWf9SmhRJpBK3qNPhaybcHPWaKYGOQw1EhRPmiA=; b=KSSQUB4XLSuiQyXSncUbHLBYPt8QoSpZjrsIJrcc123HdRU8CO0T16ia4oyMZV+ZB2yT9QmS8MX/Dy4RZAOX4NTUHJLiSDmno5PAVe5Yx3Eggpj4XLQUWhDU4RWpzIu57lC8iy55zKFY4wRQmrli98YGvOWHzoxIQTejIIjsam0= 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 1741696967570522.3887271193701; Tue, 11 Mar 2025 05:42:47 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trxrs-0004iS-5v; Tue, 11 Mar 2025 07:33:52 -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 1trxpz-00030J-FP for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:31: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 1trxps-0006Po-8g for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:31:54 -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-141-Usi3BkozOZ-SU2-v5lc-hQ-1; Tue, 11 Mar 2025 07:31:44 -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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 780C21954B3A for ; Tue, 11 Mar 2025 11:31:43 +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 EA6FE19560AB for ; Tue, 11 Mar 2025 11:31:42 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id BD8FA21E66A3; Tue, 11 Mar 2025 12:31:37 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741692705; 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=d7vRvWf9SmhRJpBK3qNPhaybcHPWaKYGOQw1EhRPmiA=; b=G6s0mvHzOgRNwwbpG/tZiLarl/o2NMg7++u1Bk1aNTfkqH2bU7C4o+7WKJUp3dZpsUPE8v zHEW8WA2E3qUz8/3JAWmEv57XAOXziINR0Qo4PoMPqBZvCmT0WfKzamRmRJtSYtBbY6Fu0 U2SMu5iVgQvkKI6mnfEaapNBqpyGNxo= X-MC-Unique: Usi3BkozOZ-SU2-v5lc-hQ-1 X-Mimecast-MFC-AGG-ID: Usi3BkozOZ-SU2-v5lc-hQ_1741692703 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 03/61] docs/qapi-domain: add QAPI domain object registry Date: Tue, 11 Mar 2025 12:30:39 +0100 Message-ID: <20250311113137.1277125-4-armbru@redhat.com> In-Reply-To: <20250311113137.1277125-1-armbru@redhat.com> References: <20250311113137.1277125-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: 1741696968750019000 Content-Type: text/plain; charset="utf-8" From: John Snow This is the first step towards QAPI domain cross-references and a QAPI reference index. This patch just creates the object registry, and updates the merge_domaindata stub method now that we have actual data we may need to merge. Note that how to handle merge conflict resolution is unhandled, as the Sphinx python domain itself does not handle it either. I do not know how to intentionally trigger it, so I've left an assertion instead if it should ever come up ... Signed-off-by: John Snow Message-ID: <20250311034303.75779-6-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 77 +++++++++++++++++++++++++++++++++++++- 1 file changed, 75 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index a1983d9444..f3ece42bc2 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -9,10 +9,12 @@ AbstractSet, Any, Dict, + NamedTuple, Tuple, ) =20 from sphinx.domains import Domain, ObjType +from sphinx.locale import __ from sphinx.util import logging =20 =20 @@ -22,22 +24,93 @@ logger =3D logging.getLogger(__name__) =20 =20 +class ObjectEntry(NamedTuple): + docname: str + node_id: str + objtype: str + aliased: bool + + class QAPIDomain(Domain): """QAPI language domain.""" =20 name =3D "qapi" label =3D "QAPI" =20 + # This table associates cross-reference object types (key) with an + # ObjType instance, which defines the valid cross-reference roles + # for each object type. + + # Actual table entries for module, command, event, etc will come in + # forthcoming commits. object_types: Dict[str, ObjType] =3D {} + directives =3D {} roles =3D {} - initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D {} + + # Moved into the data property at runtime; + # this is the internal index of reference-able objects. + initial_data: Dict[str, Dict[str, Tuple[Any]]] =3D { + "objects": {}, # fullname -> ObjectEntry + } + indices =3D [] =20 + @property + def objects(self) -> Dict[str, ObjectEntry]: + ret =3D self.data.setdefault("objects", {}) + return ret # type: ignore[no-any-return] + + def note_object( + self, + name: str, + objtype: str, + node_id: str, + aliased: bool =3D False, + location: Any =3D None, + ) -> None: + """Note a QAPI object for cross reference.""" + if name in self.objects: + other =3D self.objects[name] + if other.aliased and aliased is False: + # The original definition found. Override it! + pass + elif other.aliased is False and aliased: + # The original definition is already registered. + return + else: + # duplicated + logger.warning( + __( + "duplicate object description of %s, " + "other instance in %s, use :no-index: for one of t= hem" + ), + name, + other.docname, + location=3Dlocation, + ) + self.objects[name] =3D ObjectEntry( + self.env.docname, node_id, objtype, aliased + ) + + def clear_doc(self, docname: str) -> None: + for fullname, obj in list(self.objects.items()): + if obj.docname =3D=3D docname: + del self.objects[fullname] + def merge_domaindata( self, docnames: AbstractSet[str], otherdata: Dict[str, Any] ) -> None: - pass + for fullname, obj in otherdata["objects"].items(): + if obj.docname in docnames: + # Sphinx's own python domain doesn't appear to bother to + # check for collisions. Assert they don't happen and + # we'll fix it if/when the case arises. + assert fullname not in self.objects, ( + "bug - collision on merge?" + f" {fullname=3D} {obj=3D} {self.objects[fullname]=3D}" + ) + self.objects[fullname] =3D obj =20 def resolve_any_xref(self, *args: Any, **kwargs: Any) -> Any: # pylint: disable=3Dunused-argument --=20 2.48.1