From nobody Thu Apr 10 09:32:55 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=1741509431; cv=none; d=zohomail.com; s=zohoarc; b=jD54Rk3Un1UzPKqMOO9uhTknsDtSgNmDurUq2Klo+Qk/jlhYptYEt9oYrWYn5N1iTUn8OH++8tHc4mSsamtKfFX9NFQXAQqEbXeBEsGKfGoe+e67sYHIodFxL0jU6TQKSHgm2vsywCgOML523K29LEY3RgwZu/G24/awsUOo3po= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741509431; 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=ul87QQLe8eVy1zyM9zKQuIg5kIDNiTdHOVQOHDg4KGA=; b=TGgcYZ+v/F85JkXY2PD3TQW1F8cSJO7ebHNFMCsv3ivHSYZ15NsaYHOuztKVxidEF6emKFkdwHep9cByCC2gEzJd/00yyJBL6TykUJvYn1LMjk0SZ5x57WBohX3oqwkQjSd28GzAMRfL6TnxNgzHbwBL+/fACS7nMBeuvw/4uDo= 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 1741509431029465.9906642213441; Sun, 9 Mar 2025 00:37:11 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trC99-0001HN-O8; Sun, 09 Mar 2025 04:36:31 -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 1trC93-00018D-B7 for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:36:25 -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 1trC91-00029t-N2 for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:36:25 -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-464-AVCMDYexPwK8BUmpavYEqA-1; Sun, 09 Mar 2025 04:36:18 -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 AF82F1801A1A; Sun, 9 Mar 2025 08:36:17 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.4]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 2BEF419560AB; Sun, 9 Mar 2025 08:36:14 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741509382; 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=ul87QQLe8eVy1zyM9zKQuIg5kIDNiTdHOVQOHDg4KGA=; b=DrKJQcnqAVJ3aFj8MFTtZNAYQ9HSSTQUNxGLKze3wTzo3o19b1VjvOER0BwVhWcn9SGONb eW+raoYxizXklr9x6pil2/T0z5e2Upim8TAc8abLtIWXHmrVbb7X33fkbCDgkaZRyllfnO GKrFfNZY/FppBrsIiAfPvpYKR5EqZ7c= X-MC-Unique: AVCMDYexPwK8BUmpavYEqA-1 X-Mimecast-MFC-AGG-ID: AVCMDYexPwK8BUmpavYEqA_1741509377 From: John Snow To: qemu-devel@nongnu.org Cc: Markus Armbruster , =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Michael Roth , =?UTF-8?q?Daniel=20P=2E=20Berrang=C3=A9?= , Eric Blake , Thomas Huth , =?UTF-8?q?Alex=20Benn=C3=A9e?= , Peter Maydell , John Snow Subject: [PATCH v2 10/62] docs/qapi-domain: Add ObjectDescription abstract class Date: Sun, 9 Mar 2025 04:34:57 -0400 Message-ID: <20250309083550.5155-11-jsnow@redhat.com> In-Reply-To: <20250309083550.5155-1-jsnow@redhat.com> References: <20250309083550.5155-1-jsnow@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.133.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_H2=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: 1741509433194019000 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. Only handle_signature() is 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 | 65 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 63 insertions(+), 2 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 49d42c0921c..0365891f354 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,65 @@ def process_link( return title, target =20 =20 +Signature =3D str + + +class QAPIDescription(ObjectDescription[Signature]): + """ + Generic QAPI description. + + Abstract class, not instantiated directly. + """ + + 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. + 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, f= ullname) + 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) + ) + + class QAPIIndex(Index): """ Index subclass to provide the QAPI definition index. --=20 2.48.1