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>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <
20240717021312.606116-9-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
#
# 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",
# <- { "return": {} }
#
# .. qmp-example::
-# :title: Remove all latency histograms
+# :annotated:
+#
+# Remove all latency histograms::
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0" } }
#
# 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": [
# "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": [
# }
# ]}
#
-# 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": [
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
+# :annotated:
+#
+# ::
#
-# -> { "execute": "balloon", "arguments": { "value": 536870912 } }
-# <- { "return": {} }
+# -> { "execute": "balloon", "arguments": { "value": 536870912 } }
+# <- { "return": {} }
#
-# With a 2.5GiB guest this command inflated the ballon to 3GiB.
+# With a 2.5GiB guest this command inflated the ballon to 3GiB.
##
{ 'command': 'balloon', 'data': {'value': 'int'} }
#
# 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"} }
#
# 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" }
# }
# }
#
-# 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" }
#
# 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",
# }
# }
#
-# 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",
projects / qemu-xen.git / commitdiff