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? > @@ -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 ... [...]
