Merge tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru into staging
QAPI patches patches for 2024-07-17
# -----BEGIN PGP SIGNATURE-----
#
# iQJGBAABCAAwFiEENUvIs9frKmtoZ05fOHC0AOuRhlMFAmaXoUESHGFybWJydUBy
# ZWRoYXQuY29tAAoJEDhwtADrkYZTatYP/jPlsmx8S6X397COQf6Wd4oEFQEMo/FS
# tWFiHWenPUZ56U3O3lDNIw+5URbhF4aUpxhLGg6cmkrOwK0zPjARI2UNnUnZvPtN
# EHf//KJOpYLsSdkIlIW2nYzB27ps0DRf5PgOGdOOdW32Nuq93FLx7ChDgbpmrijc
# HzByyJIn1QEv/G0aOMLCuTPA7LpGjCAd2a/LjWYpSXB3WGizrS2Rrat7oJYUl8Rz
# mAPgdiE0aH2yWHOTcWabKfN4AsIHCnv7qNOZkumoWpZ0XULbgyK1OO05ju3jRSrB
# 0WiwiE8pEhHz7qstKGcjS1c7pPuId64ubm3RAZ1RUqVvA5TZGucwuYiuQHUVX6jH
# BGzpfojISFzIfTiKemyfqBb1gjXjxT6OIlCtmlJSUCJohb70f0fhX3vniyhzyl1d
# fFTM0jMbmBX89e/o3j6ZXa7anafYNDh5TjTK4BYeAXRqe+jZpvDJUrwu1OZIq1cd
# Wr1RR8qaawpfjD5r9SXu1mX5MPCX4SmNVNoQ7N4ruWjpVojQNmuCRW9yLPIv3yTH
# c5ESND4zdvceW5EF9f5GSIFwnIdGqnUwJyBMcULGoCxz1HougQmGR4bhqSkEl6RD
# GRK+bj3pLdj9f/en62mE6+f5rkEJye3Y5fJ5dn9+Ld09PeUtY59YKnJGg896g55V
# /pGOUWf3L4iY
# =E0F5
# -----END PGP SIGNATURE-----
# gpg: Signature made Wed 17 Jul 2024 08:47:29 PM AEST
# gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653
# gpg: issuer "armbru@redhat.com"
# gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full]
# gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full]
* tag 'pull-qapi-2024-07-17' of https://repo.or.cz/qemu/armbru:
qapi: remove "Example" doc section
qapi: convert "Example" sections with longer prose
qapi: convert "Example" sections with titles
qapi: convert "Example" sections without titles
docs/sphinx: add CSS styling for qmp-example directive
docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
docs/qapidoc: create qmp-example directive
docs/qapidoc: factor out do_parse()
qapi/ui: Drop note on naming of SpiceQueryMouseMode
qapi/sockets: Move deprecation note out of SocketAddress doc comment
qapi/machine: Clarify query-uuid value when none has been specified
qapi/machine: Clean up documentation around CpuInstanceProperties
qapi/pci: Clean up documentation around PciDeviceClass
qapi/qom: Document feature unstable of @x-vfio-user-server
Signed-off-by: Richard Henderson <richard.henderson@linaro.org>
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index ae97b33..583207a 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -899,7 +899,7 @@
~~~~~~~~~~~~~~~~~~~~
Documentation comments can use most rST markup. In particular,
-a ``::`` literal block can be used for examples::
+a ``::`` literal block can be used for pre-formatted text::
# ::
#
@@ -995,8 +995,8 @@
# @feature: Description text
A tagged section begins with a paragraph that starts with one of the
-following words: "Since:", "Example:"/"Examples:", "Returns:",
-"Errors:", "TODO:". It ends with the start of a new section.
+following words: "Since:", "Returns:", "Errors:", "TODO:". It ends with
+the start of a new section.
The second and subsequent lines of tagged sections must be indented
like this::
@@ -1020,13 +1020,53 @@
A "Since: x.y.z" tagged section lists the release that introduced the
definition.
-An "Example" or "Examples" section is rendered entirely
-as literal fixed-width text. "TODO" sections are not rendered at all
-(they are for developers, not users of QMP). In other sections, the
-text is formatted, and rST markup can be used.
+"TODO" sections are not rendered (they are for developers, not users of
+QMP). In other sections, the text is formatted, and rST markup can be
+used.
+
+QMP Examples can be added by using the ``.. qmp-example::``
+directive. In its simplest form, this can be used to contain a single
+QMP code block which accepts standard JSON syntax with additional server
+directionality indicators (``->`` and ``<-``), and elisions (``...``).
+
+Optionally, a plaintext title may be provided by using the ``:title:``
+directive option. If the title is omitted, the example title will
+default to "Example:".
+
+A simple QMP example::
+
+ # .. qmp-example::
+ # :title: Using query-block
+ #
+ # -> { "execute": "query-block" }
+ # <- { ... }
+
+More complex or multi-step examples where exposition is needed before or
+between QMP code blocks can be created by using the ``:annotated:``
+directive option. When using this option, nested QMP code blocks must be
+entered explicitly with rST's ``::`` syntax.
+
+Highlighting in non-QMP languages can be accomplished by using the
+``.. code-block:: lang`` directive, and non-highlighted text can be
+achieved by omitting the language argument.
For example::
+ # .. qmp-example::
+ # :annotated:
+ # :title: A more complex demonstration
+ #
+ # This is a more complex example that can use
+ # ``arbitrary rST syntax`` in its exposition::
+ #
+ # -> { "execute": "query-block" }
+ # <- { ... }
+ #
+ # Above, lengthy output has been omitted for brevity.
+
+
+Examples of complete definition documentation::
+
##
# @BlockStats:
#
@@ -1058,11 +1098,11 @@
#
# Since: 0.14
#
- # Example:
+ # .. qmp-example::
#
# -> { "execute": "query-blockstats" }
# <- {
- # ... lots of output ...
+ # ...
# }
##
{ 'command': 'query-blockstats',
diff --git a/docs/sphinx-static/theme_overrides.css b/docs/sphinx-static/theme_overrides.css
index c70ef95..965ecac 100644
--- a/docs/sphinx-static/theme_overrides.css
+++ b/docs/sphinx-static/theme_overrides.css
@@ -87,6 +87,55 @@
padding-bottom: 1px;
}
+/* qmp-example directive styling */
+
+.rst-content .admonition-example {
+ /* do not apply the standard admonition background */
+ background-color: transparent;
+ border: solid #ffd2ed 1px;
+}
+
+.rst-content .admonition-example > .admonition-title:before {
+ content: "▷";
+}
+
+.rst-content .admonition-example > .admonition-title {
+ background-color: #5980a6;
+}
+
+.rst-content .admonition-example > div[class^="highlight"] {
+ /* make code boxes take up the full width of the admonition w/o margin */
+ margin-left: -12px;
+ margin-right: -12px;
+
+ border-top: 1px solid #ffd2ed;
+ border-bottom: 1px solid #ffd2ed;
+ border-left: 0px;
+ border-right: 0px;
+}
+
+.rst-content .admonition-example > div[class^="highlight"]:nth-child(2) {
+ /* If a code box is the second element in an example admonition,
+ * it is the first child after the title. let it sit flush against
+ * the title. */
+ margin-top: -12px;
+ border-top: 0px;
+}
+
+.rst-content .admonition-example > div[class^="highlight"]:last-child {
+ /* If a code box is the final element in an example admonition, don't
+ * render margin below it; let it sit flush with the end of the
+ * admonition box */
+ margin-bottom: -12px;
+ border-bottom: 0px;
+}
+
+.rst-content .admonition-example .highlight {
+ background-color: #fffafd;
+}
+
+/* end qmp-example styling */
+
@media screen {
/* content column
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 62b3983..738b245 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -26,7 +26,9 @@
import os
import re
+import sys
import textwrap
+from typing import List
from docutils import nodes
from docutils.parsers.rst import Directive, directives
@@ -35,6 +37,8 @@
from qapi.gen import QAPISchemaVisitor
from qapi.schema import QAPISchema
+from sphinx import addnodes
+from sphinx.directives.code import CodeBlock
from sphinx.errors import ExtensionError
from sphinx.util.docutils import switch_source_input
from sphinx.util.nodes import nested_parse_with_titles
@@ -481,7 +485,25 @@ def visit_module(self, name):
super().visit_module(name)
-class QAPIDocDirective(Directive):
+class NestedDirective(Directive):
+ def run(self):
+ raise NotImplementedError
+
+ def do_parse(self, rstlist, node):
+ """
+ Parse rST source lines and add them to the specified node
+
+ Take the list of rST source lines rstlist, parse them as
+ rST, and add the resulting docutils nodes as children of node.
+ The nodes are parsed in a way that allows them to include
+ subheadings (titles) without confusing the rendering of
+ anything else.
+ """
+ with switch_source_input(self.state, rstlist):
+ nested_parse_with_titles(self.state, rstlist, node)
+
+
+class QAPIDocDirective(NestedDirective):
"""Extract documentation from the specified QAPI .json file"""
required_argument = 1
@@ -519,23 +541,107 @@ def run(self):
# so they are displayed nicely to the user
raise ExtensionError(str(err)) from err
- def do_parse(self, rstlist, node):
- """Parse rST source lines and add them to the specified node
- Take the list of rST source lines rstlist, parse them as
- rST, and add the resulting docutils nodes as children of node.
- The nodes are parsed in a way that allows them to include
- subheadings (titles) without confusing the rendering of
- anything else.
- """
- with switch_source_input(self.state, rstlist):
- nested_parse_with_titles(self.state, rstlist, node)
+class QMPExample(CodeBlock, NestedDirective):
+ """
+ Custom admonition for QMP code examples.
+
+ When the :annotated: option is present, the body of this directive
+ is parsed as normal rST, but with any '::' code blocks set to use
+ the QMP lexer. Code blocks must be explicitly written by the user,
+ but this allows for intermingling explanatory paragraphs with
+ arbitrary rST syntax and code blocks for more involved examples.
+
+ When :annotated: is absent, the directive body is treated as a
+ simple standalone QMP code block literal.
+ """
+
+ required_argument = 0
+ optional_arguments = 0
+ has_content = True
+ option_spec = {
+ "annotated": directives.flag,
+ "title": directives.unchanged,
+ }
+
+ def _highlightlang(self) -> addnodes.highlightlang:
+ """Return the current highlightlang setting for the document"""
+ node = None
+ doc = self.state.document
+
+ if hasattr(doc, "findall"):
+ # docutils >= 0.18.1
+ for node in doc.findall(addnodes.highlightlang):
+ pass
+ else:
+ for elem in doc.traverse():
+ if isinstance(elem, addnodes.highlightlang):
+ node = elem
+
+ if node:
+ return node
+
+ # No explicit directive found, use defaults
+ node = addnodes.highlightlang(
+ lang=self.env.config.highlight_language,
+ force=False,
+ # Yes, Sphinx uses this value to effectively disable line
+ # numbers and not 0 or None or -1 or something. ¯\_(ツ)_/¯
+ linenothreshold=sys.maxsize,
+ )
+ return node
+
+ def admonition_wrap(self, *content) -> List[nodes.Node]:
+ title = "Example:"
+ if "title" in self.options:
+ title = f"{title} {self.options['title']}"
+
+ admon = nodes.admonition(
+ "",
+ nodes.title("", title),
+ *content,
+ classes=["admonition", "admonition-example"],
+ )
+ return [admon]
+
+ def run_annotated(self) -> List[nodes.Node]:
+ lang_node = self._highlightlang()
+
+ content_node: nodes.Element = nodes.section()
+
+ # Configure QMP highlighting for "::" blocks, if needed
+ if lang_node["lang"] != "QMP":
+ content_node += addnodes.highlightlang(
+ lang="QMP",
+ force=False, # "True" ignores lexing errors
+ linenothreshold=lang_node["linenothreshold"],
+ )
+
+ self.do_parse(self.content, content_node)
+
+ # Restore prior language highlighting, if needed
+ if lang_node["lang"] != "QMP":
+ content_node += addnodes.highlightlang(**lang_node.attributes)
+
+ return content_node.children
+
+ def run(self) -> List[nodes.Node]:
+ annotated = "annotated" in self.options
+
+ if annotated:
+ content_nodes = self.run_annotated()
+ else:
+ self.arguments = ["QMP"]
+ content_nodes = super().run()
+
+ return self.admonition_wrap(*content_nodes)
def setup(app):
"""Register qapi-doc directive with Sphinx"""
app.add_config_value("qapidoc_srctree", None, "env")
app.add_directive("qapi-doc", QAPIDocDirective)
+ app.add_directive("qmp-example", QMPExample)
return {
"version": __version__,
diff --git a/qapi/acpi.json b/qapi/acpi.json
index aa4dbe5..045dab6 100644
--- a/qapi/acpi.json
+++ b/qapi/acpi.json
@@ -111,7 +111,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-acpi-ospm-status" }
# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
@@ -131,7 +131,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "ACPI_DEVICE_OST",
# "data": { "info": { "device": "d1", "slot": "0",
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 096bdbe..f400b33 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -764,7 +764,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-block" }
# <- {
@@ -1168,7 +1168,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-blockstats" }
# <- {
@@ -1461,7 +1461,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block_resize",
# "arguments": { "device": "scratch", "size": 1073741824 } }
@@ -1680,7 +1680,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-sync",
# "arguments": { "device": "ide-hd0",
@@ -1711,7 +1711,7 @@
#
# Since: 2.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-add",
# "arguments": { "driver": "qcow2",
@@ -1857,7 +1857,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-commit",
# "arguments": { "device": "virtio0",
@@ -1895,7 +1895,7 @@
#
# Since: 1.6
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "drive-backup",
# "arguments": { "device": "drive0",
@@ -1921,7 +1921,7 @@
#
# Since: 2.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-backup",
# "arguments": { "device": "src-id",
@@ -1945,7 +1945,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-named-block-nodes" }
# <- { "return": [ { "ro":false,
@@ -2126,7 +2126,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "drive-mirror",
# "arguments": { "device": "ide-hd0",
@@ -2303,7 +2303,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-add",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
@@ -2327,7 +2327,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-remove",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
@@ -2350,7 +2350,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-clear",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
@@ -2371,7 +2371,7 @@
#
# Since: 4.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-enable",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
@@ -2392,7 +2392,7 @@
#
# Since: 4.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-disable",
# "arguments": { "node": "drive0", "name": "bitmap0" } }
@@ -2424,7 +2424,7 @@
#
# Since: 4.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-dirty-bitmap-merge",
# "arguments": { "node": "drive0", "target": "bitmap0",
@@ -2533,7 +2533,7 @@
#
# Since: 2.6
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-mirror",
# "arguments": { "device": "ide-hd0",
@@ -2858,7 +2858,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-stream",
# "arguments": { "device": "virtio0",
@@ -4797,7 +4797,7 @@
#
# Since: 2.9
#
-# Examples:
+# .. qmp-example::
#
# -> { "execute": "blockdev-add",
# "arguments": {
@@ -4811,6 +4811,8 @@
# }
# <- { "return": {} }
#
+# .. qmp-example::
+#
# -> { "execute": "blockdev-add",
# "arguments": {
# "driver": "qcow2",
@@ -4895,7 +4897,7 @@
#
# Since: 2.9
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-add",
# "arguments": {
@@ -5544,7 +5546,7 @@
# .. note:: If action is "stop", a STOP event will eventually follow the
# BLOCK_IO_ERROR event.
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_IMAGE_CORRUPTED",
# "data": { "device": "", "node-name": "drive", "fatal": false,
@@ -5593,7 +5595,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_IO_ERROR",
# "data": { "device": "ide0-hd1",
@@ -5633,7 +5635,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_COMPLETED",
# "data": { "type": "stream", "device": "virtio-disk0",
@@ -5668,7 +5670,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_CANCELLED",
# "data": { "type": "stream", "device": "virtio-disk0",
@@ -5697,7 +5699,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_ERROR",
# "data": { "device": "ide0-hd1",
@@ -5732,7 +5734,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_READY",
# "data": { "device": "drive0", "type": "mirror", "speed": 0,
@@ -5760,7 +5762,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BLOCK_JOB_PENDING",
# "data": { "type": "mirror", "id": "backup_1" },
@@ -5834,7 +5836,7 @@
#
# Since: 2.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "block-set-write-threshold",
# "arguments": { "node-name": "mydev",
@@ -5879,9 +5881,8 @@
#
# Since: 2.7
#
-# Examples:
-#
-# 1. Add a new node to a quorum
+# .. qmp-example::
+# :title: Add a new node to a quorum
#
# -> { "execute": "blockdev-add",
# "arguments": {
@@ -5895,7 +5896,8 @@
# "node": "new_node" } }
# <- { "return": {} }
#
-# 2. Delete a quorum's node
+# .. qmp-example::
+# :title: Delete a quorum's node
#
# -> { "execute": "x-blockdev-change",
# "arguments": { "parent": "disk1",
@@ -5931,16 +5933,16 @@
#
# Since: 2.12
#
-# Examples:
-#
-# 1. Move a node into an IOThread
+# .. qmp-example::
+# :title: Move a node into an IOThread
#
# -> { "execute": "x-blockdev-set-iothread",
# "arguments": { "node-name": "disk1",
# "iothread": "iothread0" } }
# <- { "return": {} }
#
-# 2. Move a node into the main loop
+# .. qmp-example::
+# :title: Move a node into the main loop
#
# -> { "execute": "x-blockdev-set-iothread",
# "arguments": { "node-name": "disk1",
@@ -5985,7 +5987,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "QUORUM_FAILURE",
# "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
@@ -6016,16 +6018,16 @@
#
# Since: 2.0
#
-# Examples:
-#
-# 1. Read operation
+# .. qmp-example::
+# :title: Read operation
#
# <- { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
# "type": "read" },
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
#
-# 2. Flush operation
+# .. qmp-example::
+# :title: Flush operation
#
# <- { "event": "QUORUM_REPORT_BAD",
# "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
@@ -6070,7 +6072,7 @@
#
# Since: 1.7
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-internal-sync",
# "arguments": { "device": "ide-hd0",
@@ -6109,7 +6111,7 @@
#
# Since: 1.7
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-snapshot-delete-internal-sync",
# "arguments": { "device": "ide-hd0",
diff --git a/qapi/block.json b/qapi/block.json
index ea81d9e..ce9490a 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -117,7 +117,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
# <- { "return": {} }
@@ -161,7 +161,7 @@
#
# Since: 2.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-open-tray",
# "arguments": { "id": "ide0-1-0" } }
@@ -199,7 +199,7 @@
#
# Since: 2.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-close-tray",
# "arguments": { "id": "ide0-1-0" } }
@@ -231,7 +231,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-remove-medium",
# "arguments": { "id": "ide0-1-0" } }
@@ -272,7 +272,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "blockdev-add",
# "arguments": {
@@ -342,9 +342,8 @@
#
# Since: 2.5
#
-# Examples:
-#
-# 1. Change a removable medium
+# .. qmp-example::
+# :title: Change a removable medium
#
# -> { "execute": "blockdev-change-medium",
# "arguments": { "id": "ide0-1-0",
@@ -352,7 +351,8 @@
# "format": "raw" } }
# <- { "return": {} }
#
-# 2. Load a read-only medium into a writable drive
+# .. qmp-example::
+# :title: Load a read-only medium into a writable drive
#
# -> { "execute": "blockdev-change-medium",
# "arguments": { "id": "floppyA",
@@ -397,7 +397,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "DEVICE_TRAY_MOVED",
# "data": { "device": "ide1-cd0",
@@ -421,7 +421,7 @@
#
# Since: 3.0
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "PR_MANAGER_STATUS_CHANGED",
# "data": { "id": "pr-helper0",
@@ -463,7 +463,7 @@
#
# Since: 1.1
#
-# Examples:
+# .. qmp-example::
#
# -> { "execute": "block_set_io_throttle",
# "arguments": { "id": "virtio-blk-pci0/virtio-backend",
@@ -483,6 +483,8 @@
# "iops_size": 0 } }
# <- { "return": {} }
#
+# .. qmp-example::
+#
# -> { "execute": "block_set_io_throttle",
# "arguments": { "id": "ide0-1-0",
# "bps": 1000000,
@@ -543,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",
@@ -575,9 +583,10 @@
# "boundaries-write": [1000, 5000] } }
# <- { "return": {} }
#
-# Example:
+# .. qmp-example::
+# :annotated:
#
-# Remove all latency histograms:
+# Remove all latency histograms::
#
# -> { "execute": "block-latency-histogram-set",
# "arguments": { "id": "drive0" } }
diff --git a/qapi/char.json b/qapi/char.json
index 5eabf8e..5e4aeb9 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -40,7 +40,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-chardev" }
# <- {
@@ -86,7 +86,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-chardev-backends" }
# <- {
@@ -141,7 +141,7 @@
#
# Since: 1.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "ringbuf-write",
# "arguments": { "device": "foo",
@@ -177,7 +177,7 @@
#
# Since: 1.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "ringbuf-read",
# "arguments": { "device": "foo",
@@ -699,19 +699,23 @@
#
# Since: 1.4
#
-# Examples:
+# .. qmp-example::
#
# -> { "execute" : "chardev-add",
# "arguments" : { "id" : "foo",
# "backend" : { "type" : "null", "data" : {} } } }
# <- { "return": {} }
#
+# .. qmp-example::
+#
# -> { "execute" : "chardev-add",
# "arguments" : { "id" : "bar",
# "backend" : { "type" : "file",
# "data" : { "out" : "/tmp/bar.log" } } } }
# <- { "return": {} }
#
+# .. qmp-example::
+#
# -> { "execute" : "chardev-add",
# "arguments" : { "id" : "baz",
# "backend" : { "type" : "pty", "data" : {} } } }
@@ -735,13 +739,15 @@
#
# Since: 2.10
#
-# Examples:
+# .. qmp-example::
#
# -> { "execute" : "chardev-change",
# "arguments" : { "id" : "baz",
# "backend" : { "type" : "pty", "data" : {} } } }
# <- { "return": { "pty" : "/dev/pty/42" } }
#
+# .. qmp-example::
+#
# -> {"execute" : "chardev-change",
# "arguments" : {
# "id" : "charchannel2",
@@ -772,7 +778,7 @@
#
# Since: 1.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
# <- { "return": {} }
@@ -789,7 +795,7 @@
#
# Since: 2.10
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
# <- { "return": {} }
@@ -810,7 +816,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "VSERPORT_CHANGE",
# "data": { "id": "channel0", "open": true },
diff --git a/qapi/control.json b/qapi/control.json
index fe2af45..950443d 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -16,7 +16,7 @@
# the QMP greeting message. If the field is not provided, it
# means no QMP capabilities will be enabled. (since 2.12)
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "qmp_capabilities",
# "arguments": { "enable": [ "oob" ] } }
@@ -97,7 +97,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-version" }
# <- {
@@ -134,7 +134,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-commands" }
# <- {
@@ -165,7 +165,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "quit" }
# <- { "return": {} }
diff --git a/qapi/dump.json b/qapi/dump.json
index f9aee7e..d8145da 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -94,7 +94,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "dump-guest-memory",
# "arguments": { "paging": false, "protocol": "fd:dump" } }
@@ -150,7 +150,7 @@
#
# Since: 2.6
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-dump" }
# <- { "return": { "status": "active", "completed": 1024000,
@@ -171,7 +171,7 @@
#
# Since: 2.6
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "DUMP_COMPLETED",
# "data": { "result": { "total": 1090650112, "status": "completed",
@@ -202,7 +202,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-dump-guest-memory-capability" }
# <- { "return": { "formats":
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index a8d9ec8..7edb876 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -475,7 +475,7 @@
#
# Since: 8.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "CPU_POLARIZATION_CHANGE",
# "data": { "polarization": "horizontal" },
diff --git a/qapi/machine.json b/qapi/machine.json
index f15ad1b..f9ea6b3 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -104,7 +104,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-cpus-fast" }
# <- { "return": [
@@ -221,7 +221,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-machines", "arguments": { "compat-props": true } }
# <- { "return": [
@@ -305,9 +305,8 @@
#
# Since: 0.14
#
-# .. note:: If no UUID was specified for the guest, a null UUID is
-# returned.
-#
+# .. note:: If no UUID was specified for the guest, the nil UUID (all
+# zeroes) is returned.
##
{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@@ -320,7 +319,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-uuid" }
# <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
@@ -354,7 +353,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "system_reset" }
# <- { "return": {} }
@@ -373,7 +372,7 @@
# request or that it has shut down. Many guests will respond to this
# command by prompting the user in some way.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "system_powerdown" }
# <- { "return": {} }
@@ -393,7 +392,7 @@
# .. note:: Prior to 4.0, this command does nothing in case the guest
# isn't suspended.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "system_wakeup" }
# <- { "return": {} }
@@ -444,7 +443,7 @@
# .. note:: Prior to 2.1, this command was only supported for x86 and
# s390 VMs.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "inject-nmi" }
# <- { "return": {} }
@@ -473,7 +472,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-kvm" }
# <- { "return": { "enabled": true, "present": true } }
@@ -842,7 +841,7 @@
#
# .. caution:: Errors were not reliably returned until 1.1.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "memsave",
# "arguments": { "val": 10,
@@ -868,7 +867,7 @@
#
# .. caution:: Errors were not reliably returned until 1.1.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "pmemsave",
# "arguments": { "val": 10,
@@ -929,7 +928,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-memdev" }
# <- { "return": [
@@ -960,9 +959,7 @@
##
# @CpuInstanceProperties:
#
-# List of properties to be used for hotplugging a CPU instance, it
-# should be passed by management with device_add command when a CPU is
-# being hotplugged.
+# Properties identifying a CPU.
#
# Which members are optional and which mandatory depends on the
# architecture and board.
@@ -996,9 +993,6 @@
#
# @thread-id: thread number within the core the CPU belongs to
#
-# .. note:: Management should be prepared to pass through additional
-# properties with device_add.
-#
# Since: 2.7
##
{ 'struct': 'CpuInstanceProperties',
@@ -1020,7 +1014,8 @@
#
# @type: CPU object type for usage with device_add command
#
-# @props: list of properties to be used for hotplugging CPU
+# @props: list of properties to pass for hotplugging a CPU with
+# device_add
#
# @vcpus-count: number of logical VCPU threads @HotpluggableCPU
# provides
@@ -1028,6 +1023,9 @@
# @qom-path: link to existing CPU object if CPU is present or omitted
# if CPU is not present.
#
+# .. note:: Management should be prepared to pass through additional
+# properties with device_add.
+#
# Since: 2.7
##
{ 'struct': 'HotpluggableCPU',
@@ -1047,10 +1045,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 +1059,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 +1077,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 +1135,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'} }
@@ -1166,7 +1174,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-balloon" }
# <- { "return": {
@@ -1190,7 +1198,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "BALLOON_CHANGE",
# "data": { "actual": 944766976 },
@@ -1232,7 +1240,7 @@
#
# Since: 8.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-hv-balloon-status-report" }
# <- { "return": {
@@ -1253,7 +1261,7 @@
#
# Since: 8.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "HV_BALLOON_STATUS_REPORT",
# "data": { "committed": 816640000, "available": 3333054464 },
@@ -1285,7 +1293,7 @@
# Return the amount of initially allocated and present hotpluggable
# (if enabled) memory in bytes.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-memory-size-summary" }
# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
@@ -1564,7 +1572,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-memory-devices" }
# <- { "return": [ { "data":
@@ -1598,7 +1606,7 @@
#
# Since: 5.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
# "data": { "id": "vm0", "size": 1073741824,
@@ -1856,7 +1864,7 @@
#
# Since: 7.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "dumpdtb" }
# "arguments": { "filename": "fdt.dtb" } }
diff --git a/qapi/migration.json b/qapi/migration.json
index 1234bef..073b67c 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -287,14 +287,14 @@
#
# Since: 0.14
#
-# Examples:
-#
-# 1. Before the first migration
+# .. qmp-example::
+# :title: Before the first migration
#
# -> { "execute": "query-migrate" }
# <- { "return": {} }
#
-# 2. Migration is done and has succeeded
+# .. qmp-example::
+# :title: Migration is done and has succeeded
#
# -> { "execute": "query-migrate" }
# <- { "return": {
@@ -314,12 +314,14 @@
# }
# }
#
-# 3. Migration is done and has failed
+# .. qmp-example::
+# :title: Migration is done and has failed
#
# -> { "execute": "query-migrate" }
# <- { "return": { "status": "failed" } }
#
-# 4. Migration is being performed:
+# .. qmp-example::
+# :title: Migration is being performed
#
# -> { "execute": "query-migrate" }
# <- {
@@ -340,7 +342,8 @@
# }
# }
#
-# 5. Migration is being performed and XBZRLE is active:
+# .. qmp-example::
+# :title: Migration is being performed and XBZRLE is active
#
# -> { "execute": "query-migrate" }
# <- {
@@ -514,7 +517,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-set-capabilities" , "arguments":
# { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
@@ -532,7 +535,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-migrate-capabilities" }
# <- { "return": [
@@ -1053,7 +1056,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-set-parameters" ,
# "arguments": { "multifd-channels": 5 } }
@@ -1256,7 +1259,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-migrate-parameters" }
# <- { "return": {
@@ -1280,7 +1283,7 @@
#
# Since: 2.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-start-postcopy" }
# <- { "return": {} }
@@ -1296,7 +1299,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
# "event": "MIGRATION",
@@ -1315,7 +1318,7 @@
#
# Since: 2.6
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
# "event": "MIGRATION_PASS", "data": {"pass": 2} }
@@ -1399,7 +1402,7 @@
#
# Since: 3.1
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
# "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
@@ -1442,7 +1445,7 @@
#
# Since: 2.8
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "x-colo-lost-heartbeat" }
# <- { "return": {} }
@@ -1461,7 +1464,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate_cancel" }
# <- { "return": {} }
@@ -1477,7 +1480,7 @@
#
# Since: 2.11
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-continue" , "arguments":
# { "state": "pre-switchover" } }
@@ -1610,7 +1613,7 @@
# 6. The 'uri' and 'channels' arguments are mutually exclusive;
# exactly one of the two should be present.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
# <- { "return": {} }
@@ -1689,7 +1692,7 @@
# 5. The 'uri' and 'channels' arguments are mutually exclusive;
# exactly one of the two should be present.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-incoming",
# "arguments": { "uri": "tcp:0:4446" } }
@@ -1740,7 +1743,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-save-devices-state",
# "arguments": { "filename": "/tmp/save" } }
@@ -1758,7 +1761,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-set-global-dirty-log",
# "arguments": { "enable": true } }
@@ -1778,7 +1781,7 @@
#
# Since: 2.7
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-load-devices-state",
# "arguments": { "filename": "/tmp/resume" } }
@@ -1798,7 +1801,7 @@
# @failover: true to do failover, false to stop. Cannot be specified
# if 'enable' is true. Default value is false.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-set-replication",
# "arguments": {"enable": true, "primary": false} }
@@ -1833,7 +1836,7 @@
#
# Returns: A @ReplicationStatus object showing the status.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-xen-replication-status" }
# <- { "return": { "error": false } }
@@ -1849,7 +1852,7 @@
#
# Xen uses this command to notify replication to trigger a checkpoint.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-colo-do-checkpoint" }
# <- { "return": {} }
@@ -1887,7 +1890,7 @@
#
# Returns: A @COLOStatus object showing the status.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-colo-status" }
# <- { "return": { "mode": "primary", "last-mode": "none", "reason": "request" } }
@@ -1905,7 +1908,7 @@
#
# @uri: the URI to be used for the recovery of migration stream.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-recover",
# "arguments": { "uri": "tcp:192.168.1.200:12345" } }
@@ -1922,7 +1925,7 @@
#
# Pause a migration. Currently it only supports postcopy.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "migrate-pause" }
# <- { "return": {} }
@@ -1943,7 +1946,7 @@
#
# Since: 4.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "UNPLUG_PRIMARY",
# "data": { "device-id": "hostdev0" },
@@ -2103,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"} }
@@ -2131,15 +2137,15 @@
#
# Since: 5.2
#
-# Examples:
-#
-# 1. Measurement is in progress:
+# .. qmp-example::
+# :title: Measurement is in progress
#
# <- {"status": "measuring", "sample-pages": 512,
# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
# "calc-time-unit": "second"}
#
-# 2. Measurement has been completed:
+# .. qmp-example::
+# :title: Measurement has been completed
#
# <- {"status": "measured", "sample-pages": 512, "dirty-rate": 108,
# "mode": "page-sampling", "start-time": 1693900454, "calc-time": 10,
@@ -2182,7 +2188,7 @@
#
# Since: 7.1
#
-# Example:
+# .. qmp-example::
#
# -> {"execute": "set-vcpu-dirty-limit"}
# "arguments": { "dirty-rate": 200,
@@ -2206,7 +2212,7 @@
#
# Since: 7.1
#
-# Example:
+# .. qmp-example::
#
# -> {"execute": "cancel-vcpu-dirty-limit"},
# "arguments": { "cpu-index": 1 } }
@@ -2223,7 +2229,7 @@
#
# Since: 7.1
#
-# Example:
+# .. qmp-example::
#
# -> {"execute": "query-vcpu-dirty-limit"}
# <- {"return": [
@@ -2287,7 +2293,7 @@
#
# If @tag already exists, an error will be reported
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "snapshot-save",
# "arguments": {
@@ -2357,7 +2363,7 @@
# device nodes that can have changed since the original @snapshot-save
# command execution.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "snapshot-load",
# "arguments": {
@@ -2418,7 +2424,7 @@
# to determine completion and to fetch details of any errors that
# arise.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "snapshot-delete",
# "arguments": {
diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 2d7d4d8..8d70bd2 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -11,7 +11,7 @@
#
# Since: 2.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "rtc-reset-reinjection" }
# <- { "return": {} }
@@ -133,7 +133,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-sev" }
# <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
@@ -164,7 +164,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-sev-launch-measure" }
# <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
@@ -209,7 +209,7 @@
#
# Since: 2.12
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-sev-capabilities" }
# <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
@@ -263,7 +263,7 @@
#
# Since: 6.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute" : "query-sev-attestation-report",
# "arguments": { "mnonce": "aaaaaaa" } }
@@ -283,7 +283,7 @@
#
# Since: 2.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "dump-skeys",
# "arguments": { "filename": "/tmp/skeys" } }
@@ -328,7 +328,7 @@
#
# Since: 2.6
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-gic-capabilities" }
# <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
@@ -386,7 +386,7 @@
#
# Since: 6.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-sgx" }
# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
@@ -405,7 +405,7 @@
#
# Since: 6.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-sgx-capabilities" }
# <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
@@ -480,7 +480,7 @@
#
# Since: 8.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-event-list" }
# <- { "return": [
@@ -518,7 +518,7 @@
#
# Since: 8.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
# <- { "return": { } }
diff --git a/qapi/misc.json b/qapi/misc.json
index b04efba..4a6f3ba 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -30,7 +30,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
# "fdname": "myclient" } }
@@ -60,7 +60,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-name" }
# <- { "return": { "name": "qemu-name" } }
@@ -111,7 +111,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-iothreads" }
# <- { "return": [
@@ -144,7 +144,7 @@
# In the "suspended" state, it will completely stop the VM and cause
# a transition to the "paused" state. (Since 9.0)
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "stop" }
# <- { "return": {} }
@@ -168,7 +168,7 @@
# this command will transition back to the "suspended" state. (Since
# 9.0)
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "cont" }
# <- { "return": {} }
@@ -192,7 +192,7 @@
#
# Since: 3.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "x-exit-preconfig" }
# <- { "return": {} }
@@ -232,7 +232,7 @@
#
# * Commands that prompt the user for data don't currently work.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "human-monitor-command",
# "arguments": { "command-line": "info kvm" } }
@@ -258,7 +258,7 @@
# The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
@@ -285,7 +285,7 @@
# The 'closefd' command can be used to explicitly close the file
# descriptor when it is no longer needed.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "get-win32-socket",
# "arguments": { "info": "abcd123..", "fdname": "skclient" } }
@@ -302,7 +302,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
# <- { "return": {} }
@@ -345,7 +345,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
# <- { "return": { "fdset-id": 1, "fd": 3 } }
@@ -374,7 +374,7 @@
# .. note:: If @fd is not specified, all file descriptors in @fdset-id
# will be removed.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
# <- { "return": {} }
@@ -420,7 +420,7 @@
#
# .. note:: The list of fd sets is shared by all monitor connections.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-fdsets" }
# <- { "return": [
@@ -523,7 +523,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-command-line-options",
# "arguments": { "option": "option-rom" } }
@@ -565,7 +565,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "RTC_CHANGE",
# "data": { "offset": 78 },
@@ -592,7 +592,7 @@
#
# Since: 7.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "VFU_CLIENT_HANGUP",
# "data": { "vfu-id": "vfu1",
diff --git a/qapi/net.json b/qapi/net.json
index dd6c365..31b3417 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -26,7 +26,7 @@
# command will succeed even if the network adapter does not support
# link status notification.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "set_link",
# "arguments": { "name": "e1000.0", "up": false } }
@@ -46,7 +46,7 @@
# Errors:
# - If @type is not a valid network backend, DeviceNotFound
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "netdev_add",
# "arguments": { "type": "user", "id": "netdev1",
@@ -68,7 +68,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
# <- { "return": {} }
@@ -836,7 +836,7 @@
#
# Since: 1.6
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
# <- { "return": [
@@ -881,7 +881,7 @@
#
# Since: 1.6
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "NIC_RX_FILTER_CHANGED",
# "data": { "name": "vnet0",
@@ -930,7 +930,9 @@
# switches. This can be useful when network bonds fail-over the
# active slave.
#
-# Example:
+# TODO: This line is a hack to separate the example from the body
+#
+# .. qmp-example::
#
# -> { "execute": "announce-self",
# "arguments": {
@@ -955,7 +957,7 @@
#
# Since: 4.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "FAILOVER_NEGOTIATED",
# "data": { "device-id": "net1" },
@@ -975,7 +977,7 @@
#
# Since: 7.2
#
-# Examples:
+# .. qmp-example::
#
# <- { "event": "NETDEV_STREAM_CONNECTED",
# "data": { "netdev-id": "netdev0",
@@ -983,6 +985,8 @@
# "host": "::1", "type": "inet" } },
# "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
#
+# .. qmp-example::
+#
# <- { "event": "NETDEV_STREAM_CONNECTED",
# "data": { "netdev-id": "netdev0",
# "addr": { "path": "/tmp/qemu0", "type": "unix" } },
@@ -1001,7 +1005,7 @@
#
# Since: 7.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "NETDEV_STREAM_DISCONNECTED",
# "data": {"netdev-id": "netdev0"},
diff --git a/qapi/pci.json b/qapi/pci.json
index 8287d15..ec28f1d 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -93,7 +93,8 @@
#
# Information about the Class of a PCI device
#
-# @desc: a string description of the device's class
+# @desc: a string description of the device's class (not stable, and
+# should only be treated as informational)
#
# @class: the class code of the device
#
@@ -146,9 +147,6 @@
#
# @regions: a list of the PCI I/O regions associated with the device
#
-# .. note:: The contents of @class_info.desc are not stable and should
-# only be treated as informational.
-#
# Since: 0.14
##
{ 'struct': 'PciDeviceInfo',
@@ -182,7 +180,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-pci" }
# <- { "return": [
diff --git a/qapi/qdev.json b/qapi/qdev.json
index d031fc3..e91ca03 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -62,7 +62,7 @@
# the ``-device DEVICE,help`` command-line argument, where DEVICE
# is the device's name.
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "device_add",
# "arguments": { "driver": "e1000", "id": "net1",
@@ -104,12 +104,14 @@
#
# Since: 0.14
#
-# Examples:
+# .. qmp-example::
#
# -> { "execute": "device_del",
# "arguments": { "id": "net1" } }
# <- { "return": {} }
#
+# .. qmp-example::
+#
# -> { "execute": "device_del",
# "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
# <- { "return": {} }
@@ -130,7 +132,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "DEVICE_DELETED",
# "data": { "device": "virtio-net-pci-0",
@@ -152,7 +154,7 @@
#
# Since: 6.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
# "data": { "device": "core1",
diff --git a/qapi/qom.json b/qapi/qom.json
index 7eccd2e..7e780e1 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -59,7 +59,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "qom-list",
# "arguments": { "path": "/chardevs" } }
@@ -104,16 +104,16 @@
#
# Since: 1.2
#
-# Examples:
-#
-# 1. Use absolute path
+# .. qmp-example::
+# :title: Use absolute path
#
# -> { "execute": "qom-get",
# "arguments": { "path": "/machine/unattached/device[0]",
# "property": "hotplugged" } }
# <- { "return": false }
#
-# 2. Use partial path
+# .. qmp-example::
+# :title: Use partial path
#
# -> { "execute": "qom-get",
# "arguments": { "path": "unattached/sysbus",
@@ -139,7 +139,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "qom-set",
# "arguments": { "path": "/machine",
@@ -1028,7 +1028,8 @@
#
# Features:
#
-# @unstable: Member @x-remote-object is experimental.
+# @unstable: Members @x-remote-object and @x-vfio-user-server are
+# experimental.
#
# Since: 6.0
##
@@ -1175,7 +1176,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "object-add",
# "arguments": { "qom-type": "rng-random", "id": "rng1",
@@ -1197,7 +1198,7 @@
#
# Since: 2.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "object-del", "arguments": { "id": "rng1" } }
# <- { "return": {} }
diff --git a/qapi/replay.json b/qapi/replay.json
index d3559f9..35e0c4a 100644
--- a/qapi/replay.json
+++ b/qapi/replay.json
@@ -54,7 +54,7 @@
#
# Since: 5.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-replay" }
# <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
@@ -76,7 +76,7 @@
#
# Since: 5.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
# <- { "return": {} }
@@ -91,7 +91,7 @@
#
# Since: 5.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "replay-delete-break" }
# <- { "return": {} }
@@ -112,7 +112,7 @@
#
# Since: 5.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
# <- { "return": {} }
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 9f95e63..2e63dcb 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -30,7 +30,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
# <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
@@ -98,7 +98,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
# <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
@@ -240,7 +240,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-rocker-of-dpa-flows",
# "arguments": { "name": "sw1" } }
@@ -315,7 +315,7 @@
#
# Since: 2.4
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-rocker-of-dpa-groups",
# "arguments": { "name": "sw1" } }
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 4d40c88..287691c 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -123,7 +123,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-status" }
# <- { "return": { "running": true,
@@ -152,7 +152,7 @@
#
# Since: 0.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "SHUTDOWN",
# "data": { "guest": true, "reason": "guest-shutdown" },
@@ -168,7 +168,7 @@
#
# Since: 0.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "POWERDOWN",
# "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
@@ -189,7 +189,7 @@
#
# Since: 0.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "RESET",
# "data": { "guest": false, "reason": "guest-reset" },
@@ -204,7 +204,7 @@
#
# Since: 0.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "STOP",
# "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
@@ -218,7 +218,7 @@
#
# Since: 0.12
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "RESUME",
# "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
@@ -233,7 +233,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "SUSPEND",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
@@ -252,7 +252,7 @@
#
# Since: 1.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "SUSPEND_DISK",
# "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
@@ -267,7 +267,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "WAKEUP",
# "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
@@ -289,7 +289,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "WATCHDOG",
# "data": { "action": "reset" },
@@ -382,7 +382,7 @@
#
# Since: 2.11
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "watchdog-set-action",
# "arguments": { "action": "inject-nmi" } }
@@ -406,7 +406,7 @@
#
# Since: 6.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "set-action",
# "arguments": { "reboot": "shutdown",
@@ -433,7 +433,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "GUEST_PANICKED",
# "data": { "action": "pause" },
@@ -453,7 +453,7 @@
#
# Since: 5.0
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "GUEST_CRASHLOADED",
# "data": { "action": "run" },
@@ -469,7 +469,7 @@
#
# Since: 9.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "GUEST_PVSHUTDOWN",
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
@@ -611,7 +611,7 @@
#
# Since: 5.2
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "MEMORY_FAILURE",
# "data": { "recipient": "hypervisor",
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 4d78d2c..e76fdb9 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -179,10 +179,6 @@
#
# @type: Transport type
#
-# .. note:: This type is deprecated in favor of SocketAddress. The
-# difference between SocketAddressLegacy and SocketAddress is that
-# the latter has fewer ``{}`` on the wire.
-#
# Since: 1.3
##
{ 'union': 'SocketAddressLegacy',
@@ -193,6 +189,9 @@
'unix': 'UnixSocketAddressWrapper',
'vsock': 'VsockSocketAddressWrapper',
'fd': 'FdSocketAddressWrapper' } }
+# Note: This type is deprecated in favor of SocketAddress. The
+# difference between SocketAddressLegacy and SocketAddress is that the
+# latter has fewer ``{}`` on the wire.
##
# @SocketAddressType:
diff --git a/qapi/tpm.json b/qapi/tpm.json
index 1577b5c..a16a72e 100644
--- a/qapi/tpm.json
+++ b/qapi/tpm.json
@@ -31,7 +31,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-tpm-models" }
# <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
@@ -62,7 +62,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-tpm-types" }
# <- { "return": [ "passthrough", "emulator" ] }
@@ -168,7 +168,7 @@
#
# Since: 1.5
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-tpm" }
# <- { "return":
diff --git a/qapi/trace.json b/qapi/trace.json
index 9ebb6d9..eb5f63f 100644
--- a/qapi/trace.json
+++ b/qapi/trace.json
@@ -51,7 +51,7 @@
#
# Since: 2.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "trace-event-get-state",
# "arguments": { "name": "qemu_memalign" } }
@@ -74,7 +74,7 @@
#
# Since: 2.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "trace-event-set-state",
# "arguments": { "name": "qemu_memalign", "enable": true } }
diff --git a/qapi/transaction.json b/qapi/transaction.json
index bcb05fd..b0ae343 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -244,7 +244,7 @@
#
# Since: 1.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "transaction",
# "arguments": { "actions": [
diff --git a/qapi/ui.json b/qapi/ui.json
index 5bcccbf..5daca51 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -83,7 +83,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "set_password", "arguments": { "protocol": "vnc",
# "password": "secret" } }
@@ -144,7 +144,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
# "time": "+60" } }
@@ -186,7 +186,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "screendump",
# "arguments": { "filename": "/tmp/image" } }
@@ -273,8 +273,6 @@
# @unknown: No information is available about mouse mode used by the
# spice server.
#
-# .. note:: spice/enums.h has a SpiceMouseMode already, hence the name.
-#
# Since: 1.1
##
{ 'enum': 'SpiceQueryMouseMode',
@@ -330,7 +328,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-spice" }
# <- { "return": {
@@ -379,7 +377,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
# "event": "SPICE_CONNECTED",
@@ -405,7 +403,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_INITIALIZED",
@@ -432,7 +430,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
# "event": "SPICE_DISCONNECTED",
@@ -453,7 +451,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
# "event": "SPICE_MIGRATE_COMPLETED" }
@@ -661,7 +659,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-vnc" }
# <- { "return": {
@@ -726,7 +724,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "VNC_CONNECTED",
# "data": {
@@ -753,7 +751,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "VNC_INITIALIZED",
# "data": {
@@ -779,7 +777,7 @@
#
# Since: 0.13
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "VNC_DISCONNECTED",
# "data": {
@@ -827,7 +825,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-mice" }
# <- { "return": [
@@ -1036,7 +1034,7 @@
#
# Since: 1.3
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "send-key",
# "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
@@ -1272,9 +1270,8 @@
# property, so it is possible to map which console belongs to which
# device and display.
#
-# Examples:
-#
-# 1. Press left mouse button.
+# .. qmp-example::
+# :title: Press left mouse button
#
# -> { "execute": "input-send-event",
# "arguments": { "device": "video0",
@@ -1288,7 +1285,8 @@
# "data" : { "down": false, "button": "left" } } ] } }
# <- { "return": {} }
#
-# 2. Press ctrl-alt-del.
+# .. qmp-example::
+# :title: Press ctrl-alt-del
#
# -> { "execute": "input-send-event",
# "arguments": { "events": [
@@ -1300,7 +1298,8 @@
# "key": {"type": "qcode", "data": "delete" } } } ] } }
# <- { "return": {} }
#
-# 3. Move mouse pointer to absolute coordinates (20000, 400).
+# .. qmp-example::
+# :title: Move mouse pointer to absolute coordinates
#
# -> { "execute": "input-send-event" ,
# "arguments": { "events": [
@@ -1615,7 +1614,7 @@
#
# Since: 6.0
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "display-reload",
# "arguments": { "type": "vnc", "tls-certs": true } }
@@ -1672,7 +1671,7 @@
#
# Since: 7.1
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "display-update",
# "arguments": { "type": "vnc", "addresses":
@@ -1703,7 +1702,7 @@
#
# Since: 0.14
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "client_migrate_info",
# "arguments": { "protocol": "spice",
diff --git a/qapi/vfio.json b/qapi/vfio.json
index a0e5013..40cbcde 100644
--- a/qapi/vfio.json
+++ b/qapi/vfio.json
@@ -50,7 +50,7 @@
#
# Since: 9.1
#
-# Example:
+# .. qmp-example::
#
# <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 },
# "event": "VFIO_MIGRATION",
diff --git a/qapi/virtio.json b/qapi/virtio.json
index b91f3cd..26df8b3 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -34,7 +34,7 @@
#
# Since: 7.2
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "x-query-virtio" }
# <- { "return": [
@@ -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",
@@ -690,9 +702,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 +726,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 +851,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 +881,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 +910,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",
diff --git a/qapi/yank.json b/qapi/yank.json
index 89f2f4d..30f46c9 100644
--- a/qapi/yank.json
+++ b/qapi/yank.json
@@ -81,7 +81,7 @@
# Errors:
# - If any of the YankInstances doesn't exist, DeviceNotFound
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "yank",
# "arguments": {
@@ -104,7 +104,7 @@
#
# Returns: list of @YankInstance
#
-# Example:
+# .. qmp-example::
#
# -> { "execute": "query-yank" }
# <- { "return": [
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 6ad5663..adc85b5 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -553,7 +553,7 @@ def get_doc(self) -> 'QAPIDoc':
# Note: "sections" with two colons are left alone as
# rST markup and not interpreted as a section heading.
- # TODO: Remove this error sometime in 2025 or so
+ # TODO: Remove these errors sometime in 2025 or so
# after we've fully transitioned to the new qapidoc
# generator.
@@ -567,6 +567,14 @@ def get_doc(self) -> 'QAPIDoc':
)
raise QAPIParseError(self, emsg)
+ if 'Example' in match.group(1):
+ emsg = (
+ f"The '{match.group(1)}' section is no longer "
+ "supported. Please use the '.. qmp-example::' "
+ "directive, or other suitable markup instead."
+ )
+ raise QAPIParseError(self, emsg)
+
doc.new_tagged_section(self.info, match.group(1))
text = line[match.end():]
if text:
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index b565895..f64bf38 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -172,12 +172,17 @@
#
# Duis aute irure dolor
#
-# Example:
+# .. qmp-example::
+# :title: Ideal fast-food burger situation
#
-# -> in
-# <- out
+# -> "in"
+# <- "out"
#
-# Examples:
+# Examples::
+#
+# - Not a QMP code block
+# - Merely a preformatted code block literal
+# It isn't even an rST list.
# - *verbatim*
# - {braces}
#
@@ -199,11 +204,11 @@
# @cmd-feat1: a feature
# @cmd-feat2: another feature
#
-# Example:
+# .. qmp-example::
#
-# -> in
+# -> "this example"
#
-# <- out
+# <- "has no title"
##
{ 'command': 'cmd-boxed', 'boxed': true,
'data': 'Object',
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index a8e9456..6d24f11 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -184,13 +184,21 @@
- Ut enim ad minim veniam
Duis aute irure dolor
- section=Example
- -> in
- <- out
- section=Examples
+
+.. qmp-example::
+ :title: Ideal fast-food burger situation
+
+ -> "in"
+ <- "out"
+
+Examples::
+
+ - Not a QMP code block
+ - Merely a preformatted code block literal
+ It isn't even an rST list.
- *verbatim*
- {braces}
- section=None
+
Note::
Ceci n'est pas une note
section=Since
@@ -202,10 +210,12 @@
a feature
feature=cmd-feat2
another feature
- section=Example
- -> in
+ section=None
+.. qmp-example::
- <- out
+ -> "this example"
+
+ <- "has no title"
doc symbol=EVT_BOXED
body=
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 30d457e..cb37db6 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -217,17 +217,16 @@
Duis aute irure dolor
+Example: Ideal fast-food burger situation:
-Example
-~~~~~~~
+ -> "in"
+ <- "out"
- -> in
- <- out
+Examples:
-
-Examples
-~~~~~~~~
-
+ - Not a QMP code block
+ - Merely a preformatted code block literal
+ It isn't even an rST list.
- *verbatim*
- {braces}
@@ -261,13 +260,11 @@
"cmd-feat2"
another feature
+Example::
-Example
-~~~~~~~
+ -> "this example"
- -> in
-
- <- out
+ <- "has no title"
"EVT_BOXED" (Event)