[PULL,12/61] docs/qapi-domain: add :since: directive option

Commit Message

Markus Armbruster March 11, 2025, 11:30 a.m. UTC

From: John Snow <[e-mail]>

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 <[e-mail]>
Message-ID: <[e-mail]>
Acked-by: Markus Armbruster <[e-mail]>
Signed-off-by: Markus Armbruster <[e-mail]>
---
 docs/sphinx/qapi_domain.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

Patch

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index 547040f75a..222b420d2a 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -214,6 +214,8 @@  class QAPIObject(QAPIDescription):
         {
             # Borrowed from the Python domain:
             "module": directives.unchanged,  # Override contextual module name
+            # These are QAPI originals:
+            "since": directives.unchanged,
         }
     )
 
@@ -227,7 +229,17 @@  def get_signature_prefix(self) -> List[nodes.Node]:
 
     def get_signature_suffix(self) -> List[nodes.Node]:
         """Return a suffix to put after the object name in the signature."""
-        return []
+        ret: List[nodes.Node] = []
+
+        if "since" in self.options:
+            ret += [
+                SpaceNode(" "),
+                addnodes.desc_sig_element(
+                    "", f"(Since: {self.options['since']})"
+                ),
+            ]
+
+        return ret
 
     def handle_signature(self, sig: str, signode: desc_signature) -> Signature:
         """