docs/qapidoc: add visit_member() method

This method is used for generating the "members" of a wide variety of
things, including structs, unions, enums, alternates, etc. The field
name it uses to do so is dependent on the type of entity the "member"
belongs to.

Currently, IF conditionals for individual members are not handled or
rendered, a small regression from the prior documentation
generator. This will be fixed in a future patch.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-52-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:49 -04:00 committed by Markus Armbruster
parent 52c806cad0
commit dbf51d15fd

View file

@ -78,6 +78,16 @@ __version__ = "1.0"
class Transmogrifier:
# Field names used for different entity types:
field_types = {
"enum": "value",
"struct": "memb",
"union": "memb",
"event": "memb",
"command": "arg",
"alternate": "alt",
}
def __init__(self) -> None:
self._curr_ent: Optional[QAPISchemaDefinition] = None
self._result = StringList()
@ -88,6 +98,10 @@ class Transmogrifier:
assert self._curr_ent is not None
return self._curr_ent
@property
def member_field_type(self) -> str:
return self.field_types[self.entity.meta]
# General-purpose rST generation functions
def get_indent(self) -> str:
@ -202,6 +216,19 @@ class Transmogrifier:
self.add_lines(section.text, section.info)
self.ensure_blank_line()
def visit_member(self, section: QAPIDoc.ArgSection) -> None:
# FIXME: ifcond for members
# TODO: features for members (documented at entity-level,
# but sometimes defined per-member. Should we add such
# information to member descriptions when we can?)
assert section.text and section.member
self.generate_field(
self.member_field_type,
section.member,
section.text,
section.info,
)
def visit_feature(self, section: QAPIDoc.ArgSection) -> None:
# FIXME - ifcond for features is not handled at all yet!
# Proposal: decorate the right-hand column with some graphical