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

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 ...

[...]