Re: [PATCH v3 12/16] qapi/docs: add "Intro" section parsing

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Tue, Jun 9, 2026 at 9:39 AM Markus Armbruster <armbru@redhat.com> wrote:
>>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Add parsing for explicit Intro section syntax.
>> >
>> > A side effect of this patch is that we will (currently) always create
>> > an empty Intro section, similar to how we used to have an empty Plain
>> > section. The tests are adjusted accordingly, rendered document output
>> > does not change at all.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>> > ---
>> >  docs/devel/qapi-code-gen.rst   | 16 +++++++---------
>> >  scripts/qapi/parser.py         |  4 ++--
>> >  tests/qapi-schema/doc-good.out | 18 ++++++++++++++++++
>> >  3 files changed, 27 insertions(+), 11 deletions(-)
>> >
>> > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
>> > index 3a632b4a648..b1cc5b5f0db 100644
>> > --- a/docs/devel/qapi-code-gen.rst
>> > +++ b/docs/devel/qapi-code-gen.rst
>> > @@ -984,11 +984,11 @@ definition it documents.
>> >  When documentation is required (see pragma_ 'doc-required'), every
>> >  definition must have documentation.
>> >
>> > -Definition documentation starts with a line naming the definition,
>> > -followed by an optional overview, a description of each argument (for
>> > -commands and events), member (for structs and unions), branch (for
>> > -alternates), or value (for enums), a description of each feature (if
>> > -any), and finally optional tagged sections.
>> > +Definition documentation starts with a description naming the
>> > +definition with an optional indented overview, a description of each
>> > +argument (for commands and events), member (for structs and unions),
>> > +branch (for alternates), or value (for enums), a description of each
>> > +feature (if any), and finally optional tagged sections.
>> >
>> >  Descriptions start with '\@name:'.  The description text must be
>> >  indented like this::
>>
>> This works if we convert the entire schema in the same series.  I guess
>> that's the plan.  Is it?
>
> I still plan to do it piecemeal: I will probably send everything out
> in a big series, but you will be able to cherry-pick and stage those
> patches individually as you feel they are ready. This way, modules
> that need further revisions don't hold up the entire series and v2,
> v3, etc won't email bomb all of creation just to fix an indent in a
> single module somewhere.

We'll see.

The important bit is separating "split the initial part into intro (to
be discarded by the inliner) and non-intro (to be kept)" from purely
mechanical "make the entire initial part syntactically intro".

The transition to intro syntax will likely be bothersome for
contributors, and I feel kind of bad about it.  But I also feel we do
need to make intro syntactically obvious.  We could try to ease the pain
by silently accepting old-style patches (not using intro syntax) for a
while, then have another bulk conversion.

> I think this documentation still covers it just fine: "an optional
> indented overview". Technically the things we haven't converted just
> omit that indented overview. Those overviews just remain as
> "plaintext".

You're right.  "Optional" carries even more weight here than I thought.

> It's not perfect documentation, but the expected window where we have
> two competing systems should be quite small in the grand scheme, so I
> don't think it's worth writing docs to cover the technicalities of the
> transition.

Okay.

[...]