From nobody Thu Apr 3 09:58:37 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=1741664816; cv=none; d=zohomail.com; s=zohoarc; b=IPgEVCq67tCxxTYTngvcXzzE8OZZtcVEjuFUUFhiW7WMeLpP/NB3kt74Nk5NnDjvvaShxJT3LGBjMtb2zcVaGAcgDdCY941CsOOGI1Pug28X9iNI2sZJ5h0U7MWRwSCpdx+szVQa3Bhi2mtpABn8CpVQeExureEIBeqE9v9AzbQ= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741664816; h=Content-Type: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=rpteaVJ8E+YNwZmetFjdr3B8bXvXL8/u8nqEnnHx31Q=; b=dsRLP7K9CdHmRm1aWWJ7gyFiOKDVxHQQwxfNNmKdhJavWmKirMdY5Fww9eiCGD/pxFRSUvla0liaVHlgpLD1A+ICY9gwnVAUcDGmyPZgX179f+fyraQpsHF/LeGxhp5Ql4JJlCLVwCNy3AIHXYiti6ukwNhBw/5PjJL6S4y2acI= 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 1741664816212814.942785670862; Mon, 10 Mar 2025 20:46:56 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trqY2-0005qh-NV; Mon, 10 Mar 2025 23:44: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 1trqXr-000501-HL for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:44:44 -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 1trqXp-0002L4-UR for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:44:43 -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-677-_zFESiGcNOSJUkGqhG6-Rw-1; Mon, 10 Mar 2025 23:44:37 -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 0A0A71800257; Tue, 11 Mar 2025 03:44:36 +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 9C0C51800366; Tue, 11 Mar 2025 03:44:32 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741664680; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=rpteaVJ8E+YNwZmetFjdr3B8bXvXL8/u8nqEnnHx31Q=; b=Sh85WHY65r6glX914LjPMJnbFqFAe2a92bkouqY20FMc93FZMFuNi/Ugym4TuVWATkcIJZ HcR1NdDPGa/rCbeBhGr4Mk+HkXX2Qe8yGwdNdiALeD7cJj4hNQcUqQWzV8YFo+Jkk8u9oE I8qnAbvI6JMTMuhlZZ6v+yhQkjpONH0= X-MC-Unique: _zFESiGcNOSJUkGqhG6-Rw-1 X-Mimecast-MFC-AGG-ID: _zFESiGcNOSJUkGqhG6-Rw_1741664676 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 , Harmonie Snow Subject: [PATCH v3 25/63] docs/qapi-domain: add :ifcond: directive option Date: Mon, 10 Mar 2025 23:42:23 -0400 Message-ID: <20250311034303.75779-26-jsnow@redhat.com> In-Reply-To: <20250311034303.75779-1-jsnow@redhat.com> References: <20250311034303.75779-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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: 1741664817327019100 Add a special :ifcond: option that allows us to annotate the definition-level conditionals. The syntax of the argument is currently undefined, but it's possible we can apply better formatting in the future. Currently, we just display the ifcond string as preformatted text. Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 13 +++++++++++++ docs/sphinx/qapi_domain.py | 23 +++++++++++++++++++++-- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 5f58f1d5246..3fd326613d9 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -237,3 +237,16 @@ div[class^=3D"highlight"] pre { .qapi-deprecated::before { content: '=E2=9A=A0=EF=B8=8F '; } + +.qapi-ifcond::before { + /* gaze ye into the crystal ball to determine feature availability */ + content: '=F0=9F=94=AE '; +} + +.qapi-ifcond { + background-color: #f9f5ff; + border: solid #dac2ff 6px; + padding: 8px; + border-radius: 15px; + margin: 5px; +} diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 00fd11ebf79..4531b5d8574 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -14,6 +14,7 @@ NamedTuple, Optional, Tuple, + Union, cast, ) =20 @@ -217,6 +218,7 @@ class QAPIObject(QAPIDescription): "module": directives.unchanged, # Override contextual module = name # These are QAPI originals: "since": directives.unchanged, + "ifcond": directives.unchanged, "deprecated": directives.flag, "unstable": directives.flag, } @@ -288,9 +290,14 @@ def _add_infopips(self, contentnode: addnodes.desc_con= tent) -> None: infopips =3D nodes.container() infopips.attributes["classes"].append("qapi-infopips") =20 - def _add_pip(source: str, content: str, classname: str) -> None: + def _add_pip( + source: str, content: Union[str, List[nodes.Node]], classname:= str + ) -> None: node =3D nodes.container(source) - node.append(nodes.Text(content)) + if isinstance(content, str): + node.append(nodes.Text(content)) + else: + node.extend(content) node.attributes["classes"].extend(["qapi-infopip", classname]) infopips.append(node) =20 @@ -308,6 +315,18 @@ def _add_pip(source: str, content: str, classname: str= ) -> None: "qapi-unstable", ) =20 + if self.options.get("ifcond", ""): + ifcond =3D self.options["ifcond"] + _add_pip( + f":ifcond: {ifcond}", + [ + nodes.emphasis("", "Availability"), + nodes.Text(": "), + nodes.literal(ifcond, ifcond), + ], + "qapi-ifcond", + ) + if infopips.children: contentnode.insert(0, infopips) =20 --=20 2.48.1