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>
Reviewed-by: Markus Armbruster <arm...@redhat.com>
---
qapi/block.json | 30 +++++++++++++++++++-----------
qapi/machine.json | 30 ++++++++++++++++++++----------
qapi/migration.json | 7 +++++--
qapi/virtio.json | 24 ++++++++++++++++++------
4 files changed, 62 insertions(+), 29 deletions(-)
diff --git a/qapi/block.json b/qapi/block.json
index 5ddd061e964..ce9490a3678 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",
@@ -578,7 +584,9 @@
# <- { "return": {} }
#
# .. qmp-example::
-# :title: Remove all latency histograms
+# :annotated:
+#
+# Remove all latency histograms::
#
# -> { "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 74968a14173..073b67c0524 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
