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",
diff --git a/qapi/machine.json b/qapi/machine.json
index 83f60b319c7..0a5ffe652b7 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -1047,10 +1047,11 @@
 #
 # Since: 2.7
 #
-# Examples:
+# .. qmp-example::
+#    :annotated:
 #
-#     For pseries machine type started with -smp 2,cores=2,maxcpus=4
-#     -cpu POWER8:
+#    For pseries machine type started with
+#    ``-smp 2,cores=2,maxcpus=4 -cpu POWER8``::
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
@@ -1060,7 +1061,10 @@
 #            "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
 #        ]}
 #
-#     For pc machine type started with -smp 1,maxcpus=2:
+# .. qmp-example::
+#    :annotated:
+#
+#    For pc machine type started with ``-smp 1,maxcpus=2``::
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
@@ -1075,8 +1079,11 @@
 #          }
 #        ]}
 #
-#     For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2
-#     -cpu qemu (Since: 2.11):
+# .. qmp-example::
+#    :annotated:
+#
+#    For s390x-virtio-ccw machine type started with
+#    ``-smp 1,maxcpus=2 -cpu qemu`` (Since: 2.11)::
 #
 #     -> { "execute": "query-hotpluggable-cpus" }
 #     <- {"return": [
@@ -1130,12 +1137,15 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. qmp-example::
+#    :annotated:
 #
-#     -> { "execute": "balloon", "arguments": { "value": 536870912 } }
-#     <- { "return": {} }
+#    ::
 #
-#     With a 2.5GiB guest this command inflated the ballon to 3GiB.
+#      -> { "execute": "balloon", "arguments": { "value": 536870912 } }
+#      <- { "return": {} }
+#
+#    With a 2.5GiB guest this command inflated the ballon to 3GiB.
 ##
 { 'command': 'balloon', 'data': {'value': 'int'} }
 
diff --git a/qapi/migration.json b/qapi/migration.json
index 37ce8afa380..e208a86258a 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -2106,13 +2106,16 @@
 #
 # Since: 5.2
 #
-# Example:
+# .. qmp-example::
 #
 #     -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
 #                                                     "sample-pages": 512} }
 #     <- { "return": {} }
 #
-#     Measure dirty rate using dirty bitmap for 500 milliseconds:
+# .. qmp-example::
+#    :annotated:
+#
+#    Measure dirty rate using dirty bitmap for 500 milliseconds::
 #
 #     -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 500,
 #         "calc-time-unit": "millisecond", "mode": "dirty-bitmap"} }
diff --git a/qapi/virtio.json b/qapi/virtio.json
index d965c98ad2b..26df8b3064b 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -203,9 +203,11 @@
 #
 # Since: 7.2
 #
-# Examples:
+# .. qmp-example::
+#    :annotated:
 #
-#     1. Poll for the status of virtio-crypto (no vhost-crypto active)
+#    Poll for the status of virtio-crypto (no vhost-crypto active)
+#    ::
 #
 #     -> { "execute": "x-query-virtio-status",
 #          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend" }
@@ -261,7 +263,11 @@
 #          }
 #        }
 #
-#     2. Poll for the status of virtio-net (vhost-net is active)
+# .. qmp-example::
+#    :annotated:
+#
+#    Poll for the status of virtio-net (vhost-net is active)
+#    ::
 #
 #     -> { "execute": "x-query-virtio-status",
 #          "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend" }
@@ -568,9 +574,11 @@
 #
 # Since: 7.2
 #
-# Examples:
+# .. qmp-example::
+#    :annotated:
 #
-#     1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
+#    Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
+#    ::
 #
 #     -> { "execute": "x-query-virtio-queue-status",
 #          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
@@ -593,7 +601,11 @@
 #          }
 #        }
 #
-#     2. Get VirtQueueStatus for virtio-serial (no vhost)
+# .. qmp-example::
+#    :annotated:
+#
+#    Get VirtQueueStatus for virtio-serial (no vhost)
+#    ::
 #
 #     -> { "execute": "x-query-virtio-queue-status",
 #          "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
-- 
2.45.0

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>

On Tue, Jul 9, 2024 at 7:35 AM Markus Armbruster <armbru@redhat.com> wrote:

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

Sure, why not. I tried to minimize more complex rewrites as a rule, but
it's no problem to change the styling to taste.


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