motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 04:13:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/qapi-domain: add qapi:enum directive

Browse source 
Add the .. qapi:enum:: directive, object, and :qapi:enum:`name`
cross-reference role.

Add the :value name: field list for documenting Enum values.

Of note, also introduce a new "type" role that is intended to be used by
other QAPI object directives to cross-reference arbitrary QAPI type
names, but will exclude commands, events, and modules from
consideration.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-20-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-03-10 23:42:17 -04:00 • committed by Markus Armbruster
parent 8b77f8d573
commit 902c9b0e34
1 changed files with 26 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

26
docs/sphinx/qapi_domain.py
View file

@ -312,6 +312,23 @@ class QAPICommand(QAPIObject):
)
class QAPIEnum(QAPIObject):
"""Description of a QAPI Enum."""
doc_field_types = QAPIObject.doc_field_types.copy()
doc_field_types.extend(
[
# :value name: descr
GroupedField(
"value",
label=_("Values"),
names=("value",),
can_collapse=False,
)
]
)
class QAPIModule(QAPIDescription):
"""
Directive to mark description of a new module.
@ -431,9 +448,14 @@ class QAPIDomain(Domain):
# This table associates cross-reference object types (key) with an
# ObjType instance, which defines the valid cross-reference roles
# for each object type.
#
# e.g., the :qapi:type: cross-reference role can refer to enum,
# struct, union, or alternate objects; but :qapi:obj: can refer to
# anything. Each object also gets its own targeted cross-reference role.
object_types: Dict[str, ObjType] = {
"module": ObjType(_("module"), "mod", "any"),
"command": ObjType(_("command"), "cmd", "any"),
"enum": ObjType(_("enum"), "enum", "type", "any"),
}
# Each of these provides a rST directive,
@ -441,6 +463,7 @@ class QAPIDomain(Domain):
directives = {
"module": QAPIModule,
"command": QAPICommand,
"enum": QAPIEnum,
}
# These are all cross-reference roles; e.g.
@ -449,6 +472,9 @@ class QAPIDomain(Domain):
roles = {
"mod": QAPIXRefRole(),
"cmd": QAPIXRefRole(),
"enum": QAPIXRefRole(),
# reference any data type (excludes modules, commands, events)
"type": QAPIXRefRole(),
"any": QAPIXRefRole(), # reference *any* type of QAPI object.
}