Re: [PATCH 10/16] qapi: Fix unintended definition lists in documentation

[Peter Maydell]

On Tue, 4 Apr 2023 at 12:59, Markus Armbruster <armbru@redhat.com> wrote:
>
> rST parses something like
>
>     first line
>         second line
>
> as a definition list item, where "first line" is the term being
> defined by "second line".
>
> This bites us in a couple of places.  Here's one:
>
>     # @bps_max: total throughput limit during bursts,
>     #                     in bytes (Since 1.7)
>
> scripts/qapi/parser.py parses this into an "argument section" with
> name "bps_max" and text
>
>     total throughput limit during bursts,
>               in bytes (Since 1.7)
>
> docs/sphinx/qapidoc.py duly passes the text to the rST parser, which
> parses it as another definition list.  Comes out as nested
> definitions: term "bps_max: int (optional)" defined as term "total
> throughput limit during bursts," defined as "in bytes (Since 1.7)".
>
> rST truly is the Perl of ASCII-based markups.
>
> Fix by deleting the extra indentation.
>
> Reported-by: Peter Maydell <peter.maydell@linaro.org>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>

Reviewed-by: Peter Maydell <peter.maydell@linaro.org>

thanks
-- PMM