On Tue, Jun 9, 2026 at 9:39 AM Markus Armbruster <[email protected]> wrote: > > John Snow <[email protected]> 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 <[email protected]> > > --- > > 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. 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". 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. --js > > > @@ -1093,8 +1093,7 @@ Examples of complete definition documentation:: > > > > ## > > # @BlockStats: > > - # > > - # Statistics of a virtual block device or a block backing device. > > + # Statistics of a virtual block device or a block backing device. > > # > > # @device: If the stats are for a virtual block device, the name > > # corresponding to the virtual block device. > > @@ -1111,8 +1110,7 @@ Examples of complete definition documentation:: > > > > ## > > # @query-blockstats: > > - # > > - # Query the @BlockStats for all virtual block devices. > > + # Query the @BlockStats for all virtual block devices. > > # > > # @query-nodes: If true, the command will query all the block nodes > > # ... explain, explain ... > > [...] >
