From nobody Fri Apr 4 03:45:59 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=1741693256; cv=none; d=zohomail.com; s=zohoarc; b=Qw8+bEtUUqYhaUWmxc2+hqSg2rXfb1CAjVUeBhSNl30tF6/AOT5vXJcdbcaZm3uxec9fWTnVMaVnh0KT9L8YXbfotVF/2RMjXycB3gmcF23vdISUm3yZPpL2JUoUaGa73MlO55pGNX+tosfb3LyK6RWreR15tQF8g6sR+4RhWHU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741693256; 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=n2UvpuDlRGMy9AJ9cAmINv4qPS+gh0yoTEPLCGHQ/U4=; b=NGeRoGe3G2wIlAsn3Xuel23y/k7aDjB3SvK971aO1q1jHQ3icMXLEnq+JCdyoPrC7oF8Bq4h1+ZmSPKlb3kpHLFnXN7yOY+mPKX0mQYc/SdwXcvLgdsxW9At8qneUZmNNYUKn0oECHtYBS0i+hsFpWdumx+KHRAKpJ/G3b5i/z0= 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 1741693256081655.7797691705607; Tue, 11 Mar 2025 04:40:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trxsU-00074O-0k; Tue, 11 Mar 2025 07:34:30 -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 1trxrM-0003wC-NM for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:33:21 -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 1trxrC-0006mD-9D for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:33:20 -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-661--LcROBTZOP-paD3Yj5WrBA-1; Tue, 11 Mar 2025 07:31:56 -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-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7A74319560AB for ; Tue, 11 Mar 2025 11:31:53 +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 2CA5919560AD for ; Tue, 11 Mar 2025 11:31:53 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id 1EBFA21E64B5; Tue, 11 Mar 2025 12:31:38 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741692789; 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=n2UvpuDlRGMy9AJ9cAmINv4qPS+gh0yoTEPLCGHQ/U4=; b=d3rYA/WW/CQ9UYuLZkzs0dHtMwrUB1VldZQOjmddhKzAnt7z9Jr+zpR5KOSZWidyBp3sK9 534mPUH6iRPjYIoHrXNeZJilfg9D2odVsRJqAZONIatEmQeLxoJylu7vdHITShTZH9ErzR h51ivjxjqPHzlKcSrWnNcXkYCecGwB0= X-MC-Unique: -LcROBTZOP-paD3Yj5WrBA-1 X-Mimecast-MFC-AGG-ID: -LcROBTZOP-paD3Yj5WrBA_1741692715 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 25/61] docs/qapi-domain: add type cross-refs to field lists Date: Tue, 11 Mar 2025 12:31:01 +0100 Message-ID: <20250311113137.1277125-26-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.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, T_SPF_TEMPERROR=0.01 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: 1741693258426019100 Content-Type: text/plain; charset="utf-8" From: John Snow This commit, finally, adds cross-referencing support to various field lists; modeled tightly after Sphinx's own Python domain code. Cross-referencing support is added to type names provided to :arg:, :memb:, :returns: and :choice:. :feat:, :error: and :value:, which do not take type names, do not support this syntax. The general syntax is simple: :arg TypeName ArgName: Lorem Ipsum ... The domain will transform TypeName into :qapi:type:`TypeName` in this basic case, and also apply the ``literal`` decoration to indicate that this is a type cross-reference. For optional arguments, the special "?" suffix is used. Because "*" has special meaning in rST that would cause parsing errors, we elect to use "?" instead. The special syntax processing strips this character from the end of any type name argument and will append ", optional" to the rendered output, applying the cross-reference only to the actual type name. The intent here is that the actual syntax in doc-blocks need not change; but e.g. qapidoc.py will need to process and transform "@arg foo lorem ipsum" into ":arg type? foo: lorem ipsum" based on the schema information. Therefore, nobody should ever actually witness this intermediate syntax unless they are writing manual documentation or the doc transmogrifier breaks. For array arguments, type names can similarly be surrounded by "[]", which are stripped off and then re-appended outside of the cross-reference. Signed-off-by: John Snow Message-ID: <20250311034303.75779-28-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 9fe006eef3..06fe78ce0b 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -2,6 +2,9 @@ QAPI domain extension. """ =20 +# The best laid plans of mice and men, ... +# pylint: disable=3Dtoo-many-lines + from __future__ import annotations =20 from typing import ( @@ -116,6 +119,28 @@ def process_link( =20 return title, target =20 + def result_nodes( + self, + document: nodes.document, + env: BuildEnvironment, + node: Element, + is_ref: bool, + ) -> Tuple[List[nodes.Node], List[nodes.system_message]]: + + # node here is the pending_xref node (or whatever nodeclass was + # configured at XRefRole class instantiation time). + results: List[nodes.Node] =3D [node] + + if node.get("qapi:array"): + results.insert(0, nodes.literal("[", "[")) + results.append(nodes.literal("]", "]")) + + if node.get("qapi:optional"): + results.append(nodes.Text(", ")) + results.append(nodes.emphasis("?", "optional")) + + return results, [] + =20 # Alias for the return of handle_signature(), which is used in several pla= ces. # (In the Python domain, this is Tuple[str, str] instead.) @@ -413,6 +438,7 @@ class QAPICommand(QAPIObject): "argument", label=3D_("Arguments"), names=3D("arg",), + typerolename=3D"type", can_collapse=3DFalse, ), # :error: descr @@ -426,6 +452,7 @@ class QAPICommand(QAPIObject): GroupedField( "returnvalue", label=3D_("Return"), + rolename=3D"type", names=3D("return",), can_collapse=3DTrue, ), @@ -461,6 +488,7 @@ class QAPIAlternate(QAPIObject): "alternative", label=3D_("Alternatives"), names=3D("alt",), + typerolename=3D"type", can_collapse=3DFalse, ), ] @@ -478,6 +506,7 @@ class QAPIObjectWithMembers(QAPIObject): "member", label=3D_("Members"), names=3D("memb",), + typerolename=3D"type", can_collapse=3DFalse, ), ] --=20 2.48.1