On Fri, Mar 7, 2025 at 7:26 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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 <js...@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: > >
