John Snow <js...@redhat.com> writes:
> 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.
Would
# Add sections in source order
be clearer?
> 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.
[...]
