qapi: convert "Example" sections with titles
When an Example section has a brief explanation, convert it to a
qmp-example:: section using the :title: option.
Rule of thumb: If the title can fit on a single line and requires no rST
markup, it's a good candidate for using the :title: option of
qmp-example.
In this patch, trailing punctuation is removed from the title section
for consistent headline aesthetics. In just one case, specifics of the
example are removed to make the title read better.
See commit-4: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.
See commit+2: "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-8-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
diff --git a/qapi/virtio.json b/qapi/virtio.json
index f4323cc..d965c98 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -690,9 +690,8 @@
#
# Since: 7.2
#
-# Examples:
-#
-# 1. Get vhost_virtqueue status for vhost-crypto
+# .. qmp-example::
+# :title: Get vhost_virtqueue status for vhost-crypto
#
# -> { "execute": "x-query-virtio-vhost-queue-status",
# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
@@ -715,7 +714,8 @@
# }
# }
#
-# 2. Get vhost_virtqueue status for vhost-vsock
+# .. qmp-example::
+# :title: Get vhost_virtqueue status for vhost-vsock
#
# -> { "execute": "x-query-virtio-vhost-queue-status",
# "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
@@ -839,9 +839,8 @@
#
# Since: 7.2
#
-# Examples:
-#
-# 1. Introspect on virtio-net's VirtQueue 0 at index 5
+# .. qmp-example::
+# :title: Introspect on virtio-net's VirtQueue 0 at index 5
#
# -> { "execute": "x-query-virtio-queue-element",
# "arguments": { "path": "/machine/peripheral-anon/device[1]/virtio-backend",
@@ -870,7 +869,8 @@
# }
# }
#
-# 2. Introspect on virtio-crypto's VirtQueue 1 at head
+# .. qmp-example::
+# :title: Introspect on virtio-crypto's VirtQueue 1 at head
#
# -> { "execute": "x-query-virtio-queue-element",
# "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
@@ -898,7 +898,8 @@
# }
# }
#
-# 3. Introspect on virtio-scsi's VirtQueue 2 at head
+# .. qmp-example::
+# :title: Introspect on virtio-scsi's VirtQueue 2 at head
#
# -> { "execute": "x-query-virtio-queue-element",
# "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
