From nobody Fri Apr 4 23:27:30 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=1741664883; cv=none; d=zohomail.com; s=zohoarc; b=aJU934Rxtda0TgsQE8Hh5d5tXXFJBv1FzgTqWKB7IQ8o68CkCyZEYDYfzrgquirCR5EUTooS3gVN3ddfeTMnELH8k1ifynKJnrkcxX+yRc1B/dL9f7MuY/oNf9VJ+QAPvnWbb8r2GgqDaqKmgpGeqx8vJmqDsS6Kwd7iS0hpGEA= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741664883; 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=zwdMjwJu8ylkpK+t8VkVictceMJ1UL9aW45nygG4aiw=; b=VgFlLT3ebJOpX4O5MRvp34NFBmndrooO1IHLy/3Wc3KJMcb0pMj/YsB/NpKXrPyeOz9fHExphXnKDKzIEloCNP1IGy//GlEGdOaBNNDxO+FQacEtUk3/4c9PgVSGR2XgUgl0ZXR/HfhOYbgv52nPtZ+MzqAUEOvixhvm9JvJy3I= 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 1741664883668838.0907016155033; Mon, 10 Mar 2025 20:48:03 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trqX3-0003se-Bl; Mon, 10 Mar 2025 23:43:53 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1trqX1-0003sH-QE for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:43:51 -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 1trqX0-0002DW-5r for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:43:51 -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-681-BWsoGcYqObOuFxubB6cuKQ-1; Mon, 10 Mar 2025 23:43:46 -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 7DCA519560A3; Tue, 11 Mar 2025 03:43:45 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 085C51800366; Tue, 11 Mar 2025 03:43:42 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741664629; 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=zwdMjwJu8ylkpK+t8VkVictceMJ1UL9aW45nygG4aiw=; b=L18dE0wql+JrTSf2ej+YQJfl41SXMPn2l6zU6lJhE5u/xs1DTCkSG5uSv+dVfAw5/07qMf BumKv1Az5SHqzQkyggg7pdv8Z8Z5gGR8Tcy8oyLz+7raYbOvufj/GTRW0Ijd8nP3yOAB0R pOjJb3aSB+wTtJ1fxbzncAroDVYca7M= X-MC-Unique: BWsoGcYqObOuFxubB6cuKQ-1 X-Mimecast-MFC-AGG-ID: BWsoGcYqObOuFxubB6cuKQ_1741664625 From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , John Snow , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Michael Roth , Thomas Huth , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Markus Armbruster Subject: [PATCH v3 10/63] docs/qapi-domain: Add QAPIDescription abstract class Date: Mon, 10 Mar 2025 23:42:08 -0400 Message-ID: <20250311034303.75779-11-jsnow@redhat.com> In-Reply-To: <20250311034303.75779-1-jsnow@redhat.com> References: <20250311034303.75779-1-jsnow@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=jsnow@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_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1741664885528019100 Content-Type: text/plain; charset="utf-8" This class is a generic, top-level directive for documenting some kind of QAPI thingamajig that we expect to go into the Index. This class doesn't do much by itself, and it isn't yet associated with any particular directive. handle_signature(), _object_hierarchy_parts() and _toc_entry_name() are defined in the base class. get_index_text() and add_target_and_index() are new methods defined here; they are based heavily on the layout and format of the Python domain's general object class. Signed-off-by: John Snow --- docs/sphinx/qapi_domain.py | 101 ++++++++++++++++++++++++++++++++++++- 1 file changed, 99 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 49d42c0921c..0ee36b46448 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -14,11 +14,13 @@ NamedTuple, Optional, Tuple, + cast, ) =20 from docutils import nodes =20 -from sphinx.addnodes import pending_xref +from sphinx.addnodes import desc_signature, pending_xref +from sphinx.directives import ObjectDescription from sphinx.domains import ( Domain, Index, @@ -28,7 +30,7 @@ from sphinx.locale import _, __ from sphinx.roles import XRefRole from sphinx.util import logging -from sphinx.util.nodes import make_refnode +from sphinx.util.nodes import make_id, make_refnode =20 =20 if TYPE_CHECKING: @@ -96,6 +98,101 @@ def process_link( return title, target =20 =20 +Signature =3D str + + +class QAPIDescription(ObjectDescription[Signature]): + """ + Generic QAPI description. + + This is meant to be an abstract class, not instantiated + directly. This class handles the abstract details of indexing, the + TOC, and reference targets for QAPI descriptions. + """ + + def handle_signature(self, sig: str, signode: desc_signature) -> Signa= ture: + # Do nothing. The return value here is the "name" of the entity + # being documented; for QAPI, this is the same as the + # "signature", which is just a name. + + # Normally this method must also populate signode with nodes to + # render the signature; here we do nothing instead - the + # subclasses will handle this. + return sig + + def get_index_text(self, name: Signature) -> Tuple[str, str]: + """Return the text for the index entry of the object.""" + + # NB: this is used for the global index, not the QAPI index. + return ("single", f"{name} (QMP {self.objtype})") + + def add_target_and_index( + self, name: Signature, sig: str, signode: desc_signature + ) -> None: + # name is the return value of handle_signature. + # sig is the original, raw text argument to handle_signature. + # For QAPI, these are identical, currently. + + assert self.objtype + + # 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 + + node_id =3D make_id( + self.env, self.state.document, self.objtype, fullname + ) + signode["ids"].append(node_id) + + self.state.document.note_explicit_target(signode) + domain =3D cast(QAPIDomain, self.env.get_domain("qapi")) + domain.note_object(fullname, self.objtype, node_id, location=3Dsig= node) + + if "no-index-entry" not in self.options: + arity, indextext =3D self.get_index_text(name) + assert self.indexnode is not None + if indextext: + self.indexnode["entries"].append( + (arity, indextext, node_id, "", None) + ) + + 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(".")) + + def _toc_entry_name(self, sig_node: desc_signature) -> str: + # This controls the name in the TOC and on the sidebar. + + # This is the return type of _object_hierarchy_parts(). + toc_parts =3D cast(Tuple[str, ...], sig_node.get("_toc_parts", ())) + if not toc_parts: + return "" + + config =3D self.env.app.config + *parents, name =3D toc_parts + if config.toc_object_entries_show_parents =3D=3D "domain": + return sig_node.get("fullname", name) + 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 "" + + class QAPIIndex(Index): """ Index subclass to provide the QAPI definition index. --=20 2.48.1