John Snow <js...@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 <js...@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 <arm...@redhat.com>
