Re: [PATCH 00/12] qapi: add formal "intro" section

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Thu, Apr 23, 2026, 6:00 PM John Snow <jsnow@redhat.com> wrote:
>
>> Hiya, this is a series that explores a potential syntax for a
>> designated "Intro" section. Markus knows why I want this, but for
>> everyone else: a designated "Introduction" section is useful for the
>> desired "inliner" feature for the new QAPI doc system. Commits explain
>> a bit more. This is prep work and doesn't really change anything
>> tangibly except source code syntax for the QAPI docs.
>>
>> It is designed so that this conversion can happen incrementally with
>> no actual difference to the rendered manuals, so each QAPI module can
>> be converted one at a time for easier review and merging in an
>> arbitrary order.
>>
>> This series demonstrates conversion of just four modules; if I'm given
>> a thumbs up, I will convert the rest of QAPI, one module (or
>> maintainer stanza) per patch like how I handled adding
>> cross-references.
>>
>> John Snow (12):
>>   tests/qapi: generate output in source order
>>   qapi/docs: remove unused QAPIDoc subsection members
>>   qapi/docs: make remaining subsection members "private"
>>   qapi/docs: add "Intro" section
>>   qapi/docs: adjust stub member insertion algorithm
>>   qapi/docs: remove implicit Plain section
>>   qapi/docs: add "Intro" section parsing
>>   qapi/docs: Add rendering for INTRO sections
>>   qapi: convert intro sections for accelerator.json
>>   qapi: convert intro sections for acpi-hest.json
>>   qapi: convert intro sections for acpi.json
>>   qapi: convert intro sections for audio.json
>>
>>  docs/devel/qapi-code-gen.rst            |  17 +-
>>  docs/sphinx/qapidoc.py                  |  52 +++---
>>  qapi/accelerator.json                   |  24 +--
>>  qapi/acpi-hest.json                     |   5 +-
>>  qapi/acpi.json                          |  23 +--
>>  qapi/audio.json                         | 112 ++++---------
>>  .editorconfig                           |   1 +
>>
>
> Whoops, that snuck in by accident. Ignore! I needed some help doing the
> line wraps in qapi :)

Would it make sense as a separate patch?

>>  scripts/qapi/parser.py                  | 204 ++++++++++++++----------
>>  tests/qapi-schema/doc-good.out          |  30 ++--
>>  tests/qapi-schema/doc-missing-colon.err |   2 +-
>>  tests/qapi-schema/test-qapi.py          |  15 +-
>>  11 files changed, 239 insertions(+), 246 deletions(-)
>>
>> --
>> 2.53.0
>>
>>
>>