From nobody Fri Apr 4 03:26:39 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=1741509696; cv=none; d=zohomail.com; s=zohoarc; b=ZEjaDBc+TUaqcGhPhsUm6ErhzAzSAF1guA6hHmRu+U9FGtWdA1RaizXg+7N7E0KBnsUDx75mHJzxqPA41Y/8C+ByaKx1y51l89IAJ6AK3Hb2a0wx8kxddfD167C4F6HUOpnKOl5yu0z6rXi4ITBxHIYgkPPMsuT44EcUMODEztg= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741509696; 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=yVok9rWan7B5jXvOIyFSeD+lqTlTYIOvHpccvlJg+qE=; b=KHKwEVzAOklWaxNQE/2CZSQsd9yyYAhyX6+/Lf93Pk80Pw+8s/wCbYpaml7C+kit6p9S6L+QnTSiitcAINTI9J+mcyAZRg9mNlsQNIhFfYcYsCCWWXAquqbrE4XUPYLn5kRs6xMjrDJLK/B60qxYnN4zw7JJ/1hjEABzcr4lCdM= 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 1741509696022546.3136279417251; Sun, 9 Mar 2025 00:41:36 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trC9s-00031D-4X; Sun, 09 Mar 2025 04:37:16 -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 1trC9e-0002GB-Eh for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:37:02 -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 1trC9c-0002Q2-41 for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:37:02 -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-257-UYfbJ6xNMw2LD5uqFogcwQ-1; Sun, 09 Mar 2025 04:36:53 -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 3267818007E1; Sun, 9 Mar 2025 08:36:52 +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 1972A19560AB; Sun, 9 Mar 2025 08:36:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741509418; 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=yVok9rWan7B5jXvOIyFSeD+lqTlTYIOvHpccvlJg+qE=; b=Mb/by/4IWA30KXrkEX8NqfdsuEiENwS6uB5DHzbDF+QWqOgadJc9g67gxmbSG8uiJ+pVmO XJz+o/Jk+ARumx5ZYGi1Hv/sLUYZPC/tRVZajTfFr2cN1r5Y7f5MWYPIp+TNPM879AtsIP EkSP8RMT3VIu/oMWSDGomGCvY6xTRng= X-MC-Unique: UYfbJ6xNMw2LD5uqFogcwQ-1 X-Mimecast-MFC-AGG-ID: UYfbJ6xNMw2LD5uqFogcwQ_1741509412 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 , Harmonie Snow Subject: [PATCH v2 23/62] docs/qapi-domain: add :deprecated: directive option Date: Sun, 9 Mar 2025 04:35:10 -0400 Message-ID: <20250309083550.5155-24-jsnow@redhat.com> In-Reply-To: <20250309083550.5155-1-jsnow@redhat.com> References: <20250309083550.5155-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.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=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: 1741509698832019100 Although "deprecated" is a feature (and *will* appear in the features list), add a special :deprecated: option to generate an eye-catch that makes this information very hard to miss. (The intent is to modify qapidoc.py to add this option whenever it detects that the features list attached to a definition contains the "deprecated" entry.) - RFC: Technically, this object-level option is un-needed and could be replaced with a standard content-level directive that e.g. qapidoc.py could insert at the beginning of the content block. I've done it here as an option to demonstrate how it would be possible to do. It's a matter of taste for "where" we feel like implementing it. One benefit of doing it this way is that we can create a single containing box to set CSS style options controlling the flow of multiple infoboxes. The other way to achieve that would be to create a directive that allows us to set multiple options instead, e.g.: .. qapi:infoboxes:: deprecated unstable or possibly: .. qapi:infoboxes:: :deprecated: :unstable: For now, I've left these as top-level QAPI object options. "Hey, it works." P.S., I outsourced the CSS ;) Signed-off-by: Harmonie Snow Signed-off-by: John Snow --- docs/sphinx-static/theme_overrides.css | 25 +++++++++++++++++++++++++ docs/sphinx/qapi_domain.py | 26 ++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/th= eme_overrides.css index 965ecac54fd..3765cab1b20 100644 --- a/docs/sphinx-static/theme_overrides.css +++ b/docs/sphinx-static/theme_overrides.css @@ -208,3 +208,28 @@ div[class^=3D"highlight"] pre { color: inherit; } } + +/* QAPI domain theming */ + +.qapi-infopips { + margin-bottom: 1em; +} + +.qapi-infopip { + display: inline-block; + padding: 0em 0.5em 0em 0.5em; + margin: 0.25em; +} + +.qapi-deprecated { + background-color: #fffef5; + border: solid #fff176 6px; + font-weight: bold; + padding: 8px; + border-radius: 15px; + margin: 5px; +} + +.qapi-deprecated::before { + content: '=E2=9A=A0=EF=B8=8F '; +} diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index e84affaaec2..482f4bcde3b 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -181,6 +181,7 @@ class QAPIObject(QAPIDescription): "module": directives.unchanged, # Override contextual module = name # These are QAPI originals: "since": directives.unchanged, + "deprecated": directives.flag, } ) =20 @@ -257,6 +258,31 @@ def _object_hierarchy_parts( =20 return tuple(fullname.split(".")) =20 + def _add_infopips(self, contentnode: addnodes.desc_content) -> None: + # Add various eye-catches and things that go below the signature + # bar, but precede the user-defined content. + infopips =3D nodes.container() + infopips.attributes["classes"].append("qapi-infopips") + + def _add_pip(source: str, content: str, classname: str) -> None: + node =3D nodes.container(source) + node.append(nodes.Text(content)) + node.attributes["classes"].extend(["qapi-infopip", classname]) + infopips.append(node) + + if "deprecated" in self.options: + _add_pip( + ":deprecated:", + f"This {self.objtype} is deprecated.", + "qapi-deprecated", + ) + + if infopips.children: + contentnode.insert(0, infopips) + + def transform_content(self, content_node: addnodes.desc_content) -> No= ne: + self._add_infopips(content_node) + def _toc_entry_name(self, sig_node: desc_signature) -> str: # This controls the name in the TOC and on the sidebar. =20 --=20 2.48.1