John Snow <js...@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 <js...@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
