| Message ID | 20250305034610.960147-19-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
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! [...]
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.
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(+)