motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-08-01 14:53:54 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/qapi-domain: add :deprecated: directive option

Browse source 
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 <harmonie@gmail.com>
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-24-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-03-10 23:42:21 -04:00 • committed by Markus Armbruster
parent 3fe3349d23
commit 1a0c090a5b
2 changed files with 51 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

25
docs/sphinx-static/theme_overrides.css
View file

@ -208,3 +208,28 @@ div[class^="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: '⚠️ ';
}

26
docs/sphinx/qapi_domain.py
View file

@ -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."""