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

Add the "Choices:" 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.

RFC: In the future, it would be nice to directly inline Alternates as
part of the type information in the containing object (i.e. directly in
arguments/members) - but that's a task for another series. For now, the
branch "names" are documented just like qapidoc.py does, even though
this information is superfluous for user documentation. Room for future
improvement, but not now.

Signed-off-by: John Snow <jsnow@redhat.com>
---
 docs/sphinx/qapi_domain.py | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index 66fdeec1d37..d4120fa5ac6 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -320,6 +320,23 @@ class QAPIEnum(QAPIObject):
     )
 
 
+class QAPIAlternate(QAPIObject):
+    """Description of a QAPI Alternate."""
+
+    doc_field_types = QAPIObject.doc_field_types.copy()
+    doc_field_types.extend(
+        [
+            # :choice type name: descr
+            TypedField(
+                "choice",
+                label=_("Choices"),
+                names=("choice",),
+                can_collapse=False,
+            ),
+        ]
+    )
+
+
 class QAPIModule(SphinxDirective):
     """
     Directive to mark description of a new module.
@@ -483,6 +500,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,
@@ -491,6 +509,7 @@ class QAPIDomain(Domain):
         "module": QAPIModule,
         "command": QAPICommand,
         "enum": QAPIEnum,
+        "alternate": QAPIAlternate,
     }
 
     # These are all cross-reference roles; e.g.
@@ -500,6 +519,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.
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
> cross-reference role.
>
> Add the "Choices:" 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.

Nothing wrong with the term "choices" per se, but
docs/devel/qapi-code-gen.rst and the Python code call these things
"alternatives".  I'd prefer consistency.  Could be done as a follow-up
if that's more convenient for you.

> RFC: In the future, it would be nice to directly inline Alternates as
> part of the type information in the containing object (i.e. directly in
> arguments/members) - but that's a task for another series.

Does it make sense to talk about future inlining projects when we
haven't even gotten to the present one, yet?

>                                                            For now, the
> branch "names" are documented just like qapidoc.py does, even though
> this information is superfluous for user documentation. Room for future
> improvement, but not now.

Same as before.  Good enough!

> Signed-off-by: John Snow <jsnow@redhat.com>

On Fri, Mar 7, 2025 at 5:18 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
> > cross-reference role.
> >
> > Add the "Choices:" 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.
>
> Nothing wrong with the term "choices" per se, but
> docs/devel/qapi-code-gen.rst and the Python code call these things
> "alternatives".  I'd prefer consistency.  Could be done as a follow-up
> if that's more convenient for you.
>

Done. (Wish you'd said so sooner, though.)


>
> > RFC: In the future, it would be nice to directly inline Alternates as
> > part of the type information in the containing object (i.e. directly in
> > arguments/members) - but that's a task for another series.
>
> Does it make sense to talk about future inlining projects when we
> haven't even gotten to the present one, yet?
>

Vestigial, byebye.


>
> >                                                            For now, the
> > branch "names" are documented just like qapidoc.py does, even though
> > this information is superfluous for user documentation. Room for future
> > improvement, but not now.
>
> Same as before.  Good enough!
>
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
>

John Snow <jsnow@redhat.com> writes:

> On Fri, Mar 7, 2025 at 5:18 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Add the .. qapi:alternate:: directive, object, and qapi:alt:`name`
>> > cross-reference role.
>> >
>> > Add the "Choices:" 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.
>>
>> Nothing wrong with the term "choices" per se, but
>> docs/devel/qapi-code-gen.rst and the Python code call these things
>> "alternatives".  I'd prefer consistency.  Could be done as a follow-up
>> if that's more convenient for you.
>>
>
> Done. (Wish you'd said so sooner, though.)

Fair!

[...]