From: John Snow <jsnow@redhat.com>
Date: Tue, 11 Mar 2025 03:42:18 +0000 (-0400)
Subject: docs/qapi-domain: add qapi:alternate directive
X-Git-Tag: v10.0.0-rc0~11^2~43
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=bac3f1313c2d1dca49bd5499965d8cee0d7bb98f;p=thirdparty%2Fqemu.git

docs/qapi-domain: add qapi:alternate directive

Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
cross-reference role.

Add the "Alternatives:" field list for describing alternate choices. Like
other field lists that reference QAPI types, a forthcoming commit will
add cross-referencing support to this field.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-21-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index e399474dc5..506ed92700 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -329,6 +329,23 @@ class QAPIEnum(QAPIObject):
     )
 
 
+class QAPIAlternate(QAPIObject):
+    """Description of a QAPI Alternate."""
+
+    doc_field_types = QAPIObject.doc_field_types.copy()
+    doc_field_types.extend(
+        [
+            # :alt type name: descr
+            TypedField(
+                "alternative",
+                label=_("Alternatives"),
+                names=("alt",),
+                can_collapse=False,
+            ),
+        ]
+    )
+
+
 class QAPIModule(QAPIDescription):
     """
     Directive to mark description of a new module.
@@ -456,6 +473,7 @@ class QAPIDomain(Domain):
         "module": ObjType(_("module"), "mod", "any"),
         "command": ObjType(_("command"), "cmd", "any"),
         "enum": ObjType(_("enum"), "enum", "type", "any"),
+        "alternate": ObjType(_("alternate"), "alt", "type", "any"),
     }
 
     # Each of these provides a rST directive,
@@ -464,6 +482,7 @@ class QAPIDomain(Domain):
         "module": QAPIModule,
         "command": QAPICommand,
         "enum": QAPIEnum,
+        "alternate": QAPIAlternate,
     }
 
     # These are all cross-reference roles; e.g.
@@ -473,6 +492,7 @@ class QAPIDomain(Domain):
         "mod": QAPIXRefRole(),
         "cmd": QAPIXRefRole(),
         "enum": QAPIXRefRole(),
+        "alt": QAPIXRefRole(),
         # reference any data type (excludes modules, commands, events)
         "type": QAPIXRefRole(),
         "any": QAPIXRefRole(),  # reference *any* type of QAPI object.