From 1a0c090a5bb3f7bd526224cd166703d6c80ab1ee Mon Sep 17 00:00:00 2001 From: John Snow Date: Mon, 10 Mar 2025 23:42:21 -0400 Subject: docs/qapi-domain: add :deprecated: directive option 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 forthcoming Transmogrifier in qapidoc.py will add this option whenever it detects that the features list attached to a definition contains the "deprecated" entry. P.S., I outsourced the CSS ;) Signed-off-by: Harmonie Snow Signed-off-by: John Snow Message-ID: <20250311034303.75779-24-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) (limited to 'docs/sphinx/qapi_domain.py') diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index b11300bc85..b672ae6c50 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -217,6 +217,7 @@ class QAPIObject(QAPIDescription): "module": directives.unchanged, # Override contextual module name # These are QAPI originals: "since": directives.unchanged, + "deprecated": directives.flag, } ) @@ -280,6 +281,31 @@ class QAPIObject(QAPIDescription): return sig + 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 = nodes.container() + infopips.attributes["classes"].append("qapi-infopips") + + def _add_pip(source: str, content: str, classname: str) -> None: + node = 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) -> None: + self._add_infopips(content_node) + class QAPICommand(QAPIObject): """Description of a QAPI Command.""" -- cgit 1.4.1