| Message ID | 20250305034610.960147-50-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 6458790fe55..ed0269af27d 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": "choice", > + } > + > 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 Similar issues elsewhere are marked FIXME. Worth mentioning 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?) I guess the '?' in 'TODO?' is there because you're not sure there's anything to be done about member features. But you phrased the TODO as a question. That makes the uncertainty obvious enough, doesn't it? Suggest to delete the '?' so a grep for 'TODO:' isn't deceived. Best to grep just for 'TODO', of course. > + 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
On Fri, Mar 7, 2025 at 7:25 AM Markus Armbruster <armbru@redhat.com> wrote: > 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 6458790fe55..ed0269af27d 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": "choice", > > + } > > + > > 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 > > Similar issues elsewhere are marked FIXME. > > Worth mentioning in the commit message? > Will change, and yes. > > > > + # TODO?: features for members (documented at entity-level, > > + # but sometimes defined per-member. Should we add such > > + # information to member descriptions when we can?) > > I guess the '?' in 'TODO?' is there because you're not sure there's > anything to be done about member features. But you phrased the TODO as > a question. That makes the uncertainty obvious enough, doesn't it? > Suggest to delete the '?' so a grep for 'TODO:' isn't deceived. Best to > grep just for 'TODO', of course. > Obie-kaybie. > > > + 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 6458790fe55..ed0269af27d 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": "choice", + } + 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(+)