| Message ID | 20250309083550.5155-52-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@redhat.com> writes: > 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. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > docs/sphinx/qapidoc.py | 27 +++++++++++++++++++++++++++ > 1 file changed, 27 insertions(+) > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > index 85e7367ad79..db11c2ae933 100644 > --- a/docs/sphinx/qapidoc.py > +++ b/docs/sphinx/qapidoc.py > @@ -78,6 +78,16 @@ > > > 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 @@ def entity(self) -> QAPISchemaDefinition: > 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 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None: > self.add_lines(section.text, section.info) > self.ensure_blank_line() > > + def visit_member(self, section: QAPIDoc.ArgSection) -> None: > + # TODO: ifcond for members Make it FIXME, and ideally mention it in the commit message. > + # TODO?: features for members (documented at entity-level, > + # but sometimes defined per-member. Should we add such > + # information to member descriptions when we can?) Let's drop the '?' in 'TODO?:'. > + 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
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index 85e7367ad79..db11c2ae933 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -78,6 +78,16 @@ 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 @@ def entity(self) -> QAPISchemaDefinition: 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 @@ def visit_paragraph(self, section: QAPIDoc.Section) -> None: self.add_lines(section.text, section.info) self.ensure_blank_line() + def visit_member(self, section: QAPIDoc.ArgSection) -> None: + # TODO: 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
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. Signed-off-by: John Snow <jsnow@redhat.com> --- docs/sphinx/qapidoc.py | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+)