Add a little special markup for registering "Since:" information. Adding it as an option instead of generic content lets us hoist the information into the Signature bar, optionally put it in the index, etc.
Signed-off-by: John Snow <js...@redhat.com> --- docs/qapi/index.rst | 1 + docs/sphinx/qapi-domain.py | 27 +++++++++++++++++++++++++-- 2 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst index 5516f762a24..33b9349a3ee 100644 --- a/docs/qapi/index.rst +++ b/docs/qapi/index.rst @@ -54,6 +54,7 @@ Explicit cross-referencing syntax for QAPI modules is available with .. qapi:command:: example-command + :since: 42.0 This directive creates a QAPI command named `example-command` that appears in both the `genindex` and the `qapi-index`. As of this diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py index 2c1e60290d9..38a50318d08 100644 --- a/docs/sphinx/qapi-domain.py +++ b/docs/sphinx/qapi-domain.py @@ -4,6 +4,7 @@ from __future__ import annotations +import re from typing import ( TYPE_CHECKING, Any, @@ -86,6 +87,18 @@ def process_link( return title, target +def since_validator(param: str) -> str: + """ + Validate the `:since: X.Y` option field. + """ + match = re.match(r"[0-9]+\.[0-9]+", param) + if not match: + raise ValueError( + f":since: requires a version number in X.Y format; not {param!r}" + ) + return param + + def _nested_parse(directive: SphinxDirective, content_node: Element) -> None: """ This helper preserves error parsing context across sphinx versions. @@ -127,6 +140,8 @@ class QAPIObject(ObjectDescription[Signature]): { # Borrowed from the Python domain: "module": directives.unchanged, # Override contextual module name + # These are QAPI originals: + "since": since_validator, } ) @@ -138,9 +153,17 @@ def get_signature_prefix(self, sig: str) -> List[nodes.Node]: addnodes.desc_sig_space(), ] - def get_signature_suffix(self, sig: str) -> list[nodes.Node]: + def get_signature_suffix(self, sig: str) -> List[nodes.Node]: """Returns a suffix to put after the object name in the signature.""" - return [] + ret: List[nodes.Node] = [] + + if "since" in self.options: + ret += [ + addnodes.desc_sig_space(), + addnodes.desc_sig_element("", f"(Since: {self.options['since']})"), + ] + + return ret def handle_signature(self, sig: str, signode: desc_signature) -> Signature: """ -- 2.44.0