Re: [PATCH 7/8] qapi: convert "Example" sections with longer prose

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> These examples require longer explanations or have explanations that
> require markup to look reasonable when rendered and so use the longer
> form of the ".. qmp-example::" directive.
>
> By using the :annotated: option, the content in the example block is
> assumed *not* to be a code block literal and is instead parsed as normal
> rST - with the exception that any code literal blocks after `::` will
> assumed to be a QMP code literal block.
>
> Note: There's one title-less conversion in this patch that comes along
> for the ride because it's part of a larger "Examples" block that was
> better to convert all at once.
>
> See commit-5: "docs/qapidoc: create qmp-example directive", for a
>               detailed explanation of this custom directive syntax.
>
> See commit+1: "qapi: remove "Example" doc section" for a detailed
>               explanation of why.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  qapi/block.json     | 26 ++++++++++++++++----------
>  qapi/machine.json   | 30 ++++++++++++++++++++----------
>  qapi/migration.json |  7 +++++--
>  qapi/virtio.json    | 24 ++++++++++++++++++------
>  4 files changed, 59 insertions(+), 28 deletions(-)
>
> diff --git a/qapi/block.json b/qapi/block.json
> index 5ddd061e964..d95e9fd8140 100644
> --- a/qapi/block.json
> +++ b/qapi/block.json
> @@ -545,31 +545,37 @@
>  #
>  # Since: 4.0
>  #
> -# Example:
> +# .. qmp-example::
> +#    :annotated:
>  #
> -#     Set new histograms for all io types with intervals
> -#     [0, 10), [10, 50), [50, 100), [100, +inf):
> +#    Set new histograms for all io types with intervals
> +#    [0, 10), [10, 50), [50, 100), [100, +inf)::
>  #
>  #     -> { "execute": "block-latency-histogram-set",
>  #          "arguments": { "id": "drive0",
>  #                         "boundaries": [10, 50, 100] } }
>  #     <- { "return": {} }
>  #
> -# Example:
> +# .. qmp-example::
> +#    :annotated:
>  #
> -#     Set new histogram only for write, other histograms will remain
> -#     not changed (or not created):
> +#    Set new histogram only for write, other histograms will remain
> +#    not changed (or not created)::
>  #
>  #     -> { "execute": "block-latency-histogram-set",
>  #          "arguments": { "id": "drive0",
>  #                         "boundaries-write": [10, 50, 100] } }
>  #     <- { "return": {} }
>  #
> -# Example:
> +# .. qmp-example::
> +#    :annotated:
>  #
> -#     Set new histograms with the following intervals:
> -#       read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
> -#       write: [0, 1000), [1000, 5000), [5000, +inf)
> +#    Set new histograms with the following intervals:
> +#
> +#    - read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
> +#    - write: [0, 1000), [1000, 5000), [5000, +inf)
> +#
> +#    ::
>  #
>  #     -> { "execute": "block-latency-histogram-set",
>  #          "arguments": { "id": "drive0",
   #                         "boundaries": [10, 50, 100],
   #                         "boundaries-write": [1000, 5000] } }
   #     <- { "return": {} }
   #
   # .. qmp-example::
   #    :title: Remove all latency histograms
   #
   #     -> { "execute": "block-latency-histogram-set",
   #          "arguments": { "id": "drive0" } }
   #     <- { "return": {} }
   ##

I think using :annotated: for this one as well will look better.

[...]

Reviewed-by: Markus Armbruster <armbru@redhat.com>