On Fri, Mar 7, 2025 at 7:26 AM Markus Armbruster <armbru@redhat.com> wrote:
> John Snow <jsnow@redhat.com> writes:
>
> > Implement the actual main dispatch method that processes and handles the
> > list of doc sections for a given QAPI entity.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> > docs/sphinx/qapidoc.py | 25 +++++++++++++++++++++++++
> > 1 file changed, 25 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index ed0269af27d..7308fa0a767 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -288,6 +288,31 @@ def preamble(self, ent: QAPISchemaDefinition) ->
> None:
> >
> > self.ensure_blank_line()
> >
> > + def visit_sections(self, ent: QAPISchemaDefinition) -> None:
> > + sections = ent.doc.all_sections if ent.doc else []
> > +
> > + # Add sections *in the order they are documented*:
>
> Is the order important, or just a matter of style?
>
I meant to emphasize the fact that the transmogrifier works "dumbly" on a
sequence of sections and nothing else; so the output is strictly in source
order.
The order does wind up mattering a *little*; if you randomized the section
order you'd not get good field list grouping, and/or the grouping
mechanisms would re-order the documentation so that it wasn't source order
anymore.
Not that this would happen with our parser, but, you asked.
>
> > + for section in sections:
> > + if section.kind == QAPIDoc.Kind.PLAIN:
> > + self.visit_paragraph(section)
> > + elif section.kind == QAPIDoc.Kind.MEMBER:
> > + assert isinstance(section, QAPIDoc.ArgSection)
> > + self.visit_member(section)
> > + elif section.kind == QAPIDoc.Kind.FEATURE:
> > + assert isinstance(section, QAPIDoc.ArgSection)
> > + self.visit_feature(section)
> > + elif section.kind in (QAPIDoc.Kind.SINCE,
> QAPIDoc.Kind.TODO):
> > + # Since is handled in preamble, TODO is skipped
> intentionally.
> > + pass
> > + elif section.kind == QAPIDoc.Kind.RETURNS:
> > + self.visit_returns(section)
> > + elif section.kind == QAPIDoc.Kind.ERRORS:
> > + self.visit_errors(section)
> > + else:
> > + assert False
> > +
> > + self.ensure_blank_line()
> > +
> > # Transmogrification core methods
> >
> > def visit_module(self, path: str) -> None:
>
>