QAPIDoc Total Section Ordering

QAPIDoc Total Section Ordering

[John Snow]

Hi, let's recap...

In general, it would be nice to have a strict inter-section ordering
for a few reasons:

(1) It makes it easier to add generated sections such as return
values, undocumented members, or undocumented features/flags (such as
Out-of-band execution), because there is a clear and obvious place
where we should insert the generated doc. We have a few spots in the
code now where we have a bespoke algorithm to find the correct
insertion point, and it would be nice to consolidate this logic.

(2) It makes the inliner easier, because merging two doc sections is
more obvious when there is a normal order that must be adhered to;
fields that are absent in one or the other docs list do not cause
problems or complex edge cases.

(3) It allows us to design around a unified look and layout in the
HTML generator, which increases visual cohesion and yadda yadda yadda.
In particular, each "group" of doc types is laid out in a block where
having multiple fields of the same type be non-contiguous greatly
increases visual clutter. i.e. all arguments should be contiguous, all
features should be contiguous, etc. I have in the past referred to
these groupings of doc section types as "doc regions".

For these reasons, I'd like to nail down the order once and for all,
and clarify a few things.

The order I think you prefer is something like this:

(1) Introduction ("Plain text", currently) - Always the first section,
always precisely one section. (But may be multiple paragraphs housed
within that single section.)
(2) Arguments/members/values/alternatives
(3) Return(s)
(4) Error(s)
(5) Feature(s)
(6) Details ("Plain text", currently - generally used for clarifying
detail, examples, and other information.)

Before I go any further, is this order "roughly correct" to you?

...

We previously discussed prohibiting "plain text" from appearing
anywhere except in (1) or (6). From memory, the summary of that
discussion is:

Me: Prohibiting plaintext from appearing between 2-5 makes inlining
easier, and improves HTML output by preventing plaintext paragraphs
from interrupting the "tabular" output used to render metadata fields.

You: Although it is not often utilized, we may want the freedom/power
to use plaintext paragraphs to add addendums/notes attached to
specific sections, i.e. adding a "Note:" to the tail of the arguments
section specifically.

I recall we debated this particular restriction quite a few times and
at length; does this summary sound roughly accurate as far as you
remember?

Re: QAPIDoc Total Section Ordering

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> Hi, let's recap...
>
> In general, it would be nice to have a strict inter-section ordering
> for a few reasons:
>
> (1) It makes it easier to add generated sections such as return
> values, undocumented members, or undocumented features/flags (such as
> Out-of-band execution), because there is a clear and obvious place
> where we should insert the generated doc. We have a few spots in the
> code now where we have a bespoke algorithm to find the correct
> insertion point, and it would be nice to consolidate this logic.
>
> (2) It makes the inliner easier, because merging two doc sections is
> more obvious when there is a normal order that must be adhered to;
> fields that are absent in one or the other docs list do not cause
> problems or complex edge cases.
>
> (3) It allows us to design around a unified look and layout in the
> HTML generator, which increases visual cohesion and yadda yadda yadda.
> In particular, each "group" of doc types is laid out in a block where
> having multiple fields of the same type be non-contiguous greatly
> increases visual clutter. i.e. all arguments should be contiguous, all
> features should be contiguous, etc. I have in the past referred to
> these groupings of doc section types as "doc regions".
>
> For these reasons, I'd like to nail down the order once and for all,
> and clarify a few things.
>
> The order I think you prefer is something like this:
>
> (1) Introduction ("Plain text", currently) - Always the first section,
> always precisely one section. (But may be multiple paragraphs housed
> within that single section.)
> (2) Arguments/members/values/alternatives
> (3) Return(s)
> (4) Error(s)
> (5) Feature(s)
> (6) Details ("Plain text", currently - generally used for clarifying
> detail, examples, and other information.)

  (7) Since

> Before I go any further, is this order "roughly correct" to you?

Yes!

> ...
>
> We previously discussed prohibiting "plain text" from appearing
> anywhere except in (1) or (6). From memory, the summary of that
> discussion is:
>
> Me: Prohibiting plaintext from appearing between 2-5 makes inlining
> easier, and improves HTML output by preventing plaintext paragraphs
> from interrupting the "tabular" output used to render metadata fields.
>
> You: Although it is not often utilized, we may want the freedom/power
> to use plaintext paragraphs to add addendums/notes attached to
> specific sections, i.e. adding a "Note:" to the tail of the arguments
> section specifically.
>
> I recall we debated this particular restriction quite a few times and
> at length; does this summary sound roughly accurate as far as you
> remember?

It does.

What breaks right now if you prohibit untagged sections between (2) to
(5)?

Re: QAPIDoc Total Section Ordering

[John Snow]

[-- Attachment #1: Type: text/plain, Size: 3678 bytes --]

On Wed, Mar 4, 2026, 5:46 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > Hi, let's recap...
> >
> > In general, it would be nice to have a strict inter-section ordering
> > for a few reasons:
> >
> > (1) It makes it easier to add generated sections such as return
> > values, undocumented members, or undocumented features/flags (such as
> > Out-of-band execution), because there is a clear and obvious place
> > where we should insert the generated doc. We have a few spots in the
> > code now where we have a bespoke algorithm to find the correct
> > insertion point, and it would be nice to consolidate this logic.
> >
> > (2) It makes the inliner easier, because merging two doc sections is
> > more obvious when there is a normal order that must be adhered to;
> > fields that are absent in one or the other docs list do not cause
> > problems or complex edge cases.
> >
> > (3) It allows us to design around a unified look and layout in the
> > HTML generator, which increases visual cohesion and yadda yadda yadda.
> > In particular, each "group" of doc types is laid out in a block where
> > having multiple fields of the same type be non-contiguous greatly
> > increases visual clutter. i.e. all arguments should be contiguous, all
> > features should be contiguous, etc. I have in the past referred to
> > these groupings of doc section types as "doc regions".
> >
> > For these reasons, I'd like to nail down the order once and for all,
> > and clarify a few things.
> >
> > The order I think you prefer is something like this:
> >
> > (1) Introduction ("Plain text", currently) - Always the first section,
> > always precisely one section. (But may be multiple paragraphs housed
> > within that single section.)
> > (2) Arguments/members/values/alternatives
> > (3) Return(s)
> > (4) Error(s)
> > (5) Feature(s)
> > (6) Details ("Plain text", currently - generally used for clarifying
> > detail, examples, and other information.)
>
>   (7) Since
>

Ah, right. Because I remove "since" from the flow of the document, I wind
up caring about it less, but yes. It can be last in the source.


> > Before I go any further, is this order "roughly correct" to you?
>
> Yes!
>
> > ...
> >
> > We previously discussed prohibiting "plain text" from appearing
> > anywhere except in (1) or (6). From memory, the summary of that
> > discussion is:
> >
> > Me: Prohibiting plaintext from appearing between 2-5 makes inlining
> > easier, and improves HTML output by preventing plaintext paragraphs
> > from interrupting the "tabular" output used to render metadata fields.
> >
> > You: Although it is not often utilized, we may want the freedom/power
> > to use plaintext paragraphs to add addendums/notes attached to
> > specific sections, i.e. adding a "Note:" to the tail of the arguments
> > section specifically.
> >
> > I recall we debated this particular restriction quite a few times and
> > at length; does this summary sound roughly accurate as far as you
> > remember?
>
> It does.
>
> What breaks right now if you prohibit untagged sections between (2) to
> (5)?
>

Not much. I think we have an interloping plaintext section maybe once or
twice in the docs currently. In my previous patches, I just removed those
sections but there was some concern about the ability to annotate e.g.
arguments sections with a note.

I haven't actually worked on this feature, but I suggested once we could
add an "addendum" or "section-note" tag to include these. I don't currently
have a strong sense of how hard that would or wouldn't be.

>

[-- Attachment #2: Type: text/html, Size: 5027 bytes --]

Re: QAPIDoc Total Section Ordering

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Wed, Mar 4, 2026, 5:46 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Hi, let's recap...
>> >
>> > In general, it would be nice to have a strict inter-section ordering
>> > for a few reasons:
>> >
>> > (1) It makes it easier to add generated sections such as return
>> > values, undocumented members, or undocumented features/flags (such as
>> > Out-of-band execution), because there is a clear and obvious place
>> > where we should insert the generated doc. We have a few spots in the
>> > code now where we have a bespoke algorithm to find the correct
>> > insertion point, and it would be nice to consolidate this logic.
>> >
>> > (2) It makes the inliner easier, because merging two doc sections is
>> > more obvious when there is a normal order that must be adhered to;
>> > fields that are absent in one or the other docs list do not cause
>> > problems or complex edge cases.
>> >
>> > (3) It allows us to design around a unified look and layout in the
>> > HTML generator, which increases visual cohesion and yadda yadda yadda.
>> > In particular, each "group" of doc types is laid out in a block where
>> > having multiple fields of the same type be non-contiguous greatly
>> > increases visual clutter. i.e. all arguments should be contiguous, all
>> > features should be contiguous, etc. I have in the past referred to
>> > these groupings of doc section types as "doc regions".
>> >
>> > For these reasons, I'd like to nail down the order once and for all,
>> > and clarify a few things.
>> >
>> > The order I think you prefer is something like this:
>> >
>> > (1) Introduction ("Plain text", currently) - Always the first section,
>> > always precisely one section. (But may be multiple paragraphs housed
>> > within that single section.)
>> > (2) Arguments/members/values/alternatives
>> > (3) Return(s)
>> > (4) Error(s)
>> > (5) Feature(s)
>> > (6) Details ("Plain text", currently - generally used for clarifying
>> > detail, examples, and other information.)
>>
>>   (7) Since
>>
>
> Ah, right. Because I remove "since" from the flow of the document, I wind
> up caring about it less, but yes. It can be last in the source.
>
>
>> > Before I go any further, is this order "roughly correct" to you?
>>
>> Yes!
>>
>> > ...
>> >
>> > We previously discussed prohibiting "plain text" from appearing
>> > anywhere except in (1) or (6). From memory, the summary of that
>> > discussion is:
>> >
>> > Me: Prohibiting plaintext from appearing between 2-5 makes inlining
>> > easier, and improves HTML output by preventing plaintext paragraphs
>> > from interrupting the "tabular" output used to render metadata fields.
>> >
>> > You: Although it is not often utilized, we may want the freedom/power
>> > to use plaintext paragraphs to add addendums/notes attached to
>> > specific sections, i.e. adding a "Note:" to the tail of the arguments
>> > section specifically.

Let me elaborate.

The sections in question are (2) member descriptions, (3) return, (4)
errors, and (5) feature descriptions.

Member descriptions have one section per member.  They get shown
together as a list.

Feature descriptions are similar.

Errors are in a single section.  By convention it contains a list.

Return contains just a description.  If we even inline return type
documentation, we'll get a list instead.

Each section has an indented body.  Multiple paragraphs there are rare,
but possible.  Much ReST markup just works.  Should be good enough to
document individual things.

My concern is where to put text that spans things.  Say text that
explains how multiple members are related.  Sometimes, explaining it in
just one of the member descriptions is fine.  Sometimes, explaining it
in each of the member descriptions is fine.  Sometimes, we'd really
prefer to explain it in one place after the member descriptions.

We can already put it in (6) details, but that can be rather distant
from the member descriptions.  Thus, my reluctance to lose the means to
put it right after the member descriptions.

I understand that this complicates your job, and splits the table you
generate for (2) ... (5).

Perhaps it could be useful to ponder how we'd want this to look in the
rendered table, then try to work backwards to doc syntax.

>> > I recall we debated this particular restriction quite a few times and
>> > at length; does this summary sound roughly accurate as far as you
>> > remember?
>>
>> It does.
>>
>> What breaks right now if you prohibit untagged sections between (2) to
>> (5)?
>>
>
> Not much. I think we have an interloping plaintext section maybe once or
> twice in the docs currently. In my previous patches, I just removed those
> sections but there was some concern about the ability to annotate e.g.
> arguments sections with a note.

Can you pinpoint the existing interlopers cheaply?

> I haven't actually worked on this feature, but I suggested once we could
> add an "addendum" or "section-note" tag to include these. I don't currently
> have a strong sense of how hard that would or wouldn't be.

Keep in mind that the current doc syntax grew out of lose convention in
multiple steps, where in each step we usually picked minimizing doc
churn over cleaner and more robust syntax.

This also led to a parser that was too hard to maintain.  So I rewrote
it.  It's still unlikable.

I'm not attached to the status quo there.