qapi: convert example sections to qmp-example rST directives
cover qapi: convert example sections to qmp-example rST directives
GitLab: https://gitlab.com/jsnow/qemu/-/pipelines/1359714660
This patchset focuses on converting example sections to rST directives using a new .. qmp-example:: directive.
It is based on what I *assume* will be Markus' next pull request that covers note conversion. Pull these patches from GitLab directly if that's too annoying:
https://gitlab.com/jsnow/qemu/-/commits/sphinx-domain-prereqs-examples
It is also annoyingly the case that both Markus' next pull request and this series conflicts with a separate series I sent out, "docs/python:
bump minimum Sphinx version" - so it's extremely likely I'll need to rebase and respin this series depending on what goes in and in what order. Ah well...
Changes since this was split out from the prior series:
- Harmonie updated the CSS for the example block section.
I think it's really tidy now! Thanks Harmonie!
- Dependence on SphinxDirective was removed, but it will likely re-appear in the next series anyway.
- qapi-code-gen.rst was updated with a section on how to write examples.
- Various minor tweaks to comments, commit messages, docs, etc.
Harmonie Snow (1):
docs/sphinx: add CSS styling for qmp-example directive
John Snow (7):
docs/qapidoc: factor out do_parse()
docs/qapidoc: create qmp-example directive docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
qapi: convert "Example" sections without titles
qapi: convert "Example" sections with titles
qapi: convert "Example" sections with longer prose
qapi: remove "Example" doc section
docs/devel/qapi-code-gen.rst | 58 +++++++-- docs/sphinx-static/theme_overrides.css | 49 ++++++++ docs/sphinx/qapidoc.py | 156 +++++++++++++++++++++---- qapi/acpi.json | 4 +- qapi/block-core.json | 88 +++++++------- qapi/block.json | 57 +++++---- qapi/char.json | 24 ++-- qapi/control.json | 8 +- qapi/dump.json | 8 +- qapi/machine-target.json | 2 +- qapi/machine.json | 68 ++++++----- qapi/migration.json | 90 +++++++------- qapi/misc-target.json | 22 ++-- qapi/misc.json | 32 ++--- qapi/net.json | 20 ++-- qapi/pci.json | 2 +- qapi/qdev.json | 10 +- qapi/qom.json | 16 +-- qapi/replay.json | 8 +- qapi/rocker.json | 8 +- qapi/run-state.json | 30 ++--- qapi/tpm.json | 6 +- qapi/trace.json | 4 +- qapi/transaction.json | 2 +- qapi/ui.json | 45 +++---- qapi/vfio.json | 2 +- qapi/virtio.json | 45 ++++--- qapi/yank.json | 4 +- scripts/qapi/parser.py | 10 +- tests/qapi-schema/doc-good.json | 19 +-- tests/qapi-schema/doc-good.out | 26 +++-- tests/qapi-schema/doc-good.txt | 23 ++-- 32 files changed, 605 insertions(+), 341 deletions(-)
Signature · 1 line
2.45.0
PATCH 1/8 docs/qapidoc: factor out do_parse()
Factor out the compatibility parser helper into a base class, so it can be shared by other directives.
--- docs/sphinx/qapidoc.py | 64 +++++++++++++++++++++++------------------- 1 file changed, 35 insertions(+), 29 deletions(-)
docs/sphinx/qapidoc.py +35 -29
@@ -494,7 +494,41 @@ 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. + """ + # This is from kerneldoc.py -- it works around an API change in + # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use + # sphinx.util.nodes.nested_parse_with_titles() rather than the + # plain self.state.nested_parse(), and so we can drop the saving + # of title_styles and section_level that kerneldoc.py does, + # because nested_parse_with_titles() does that for us. + if USE_SSI: + with switch_source_input(self.state, rstlist): + nested_parse_with_titles(self.state, rstlist, node) + else: + save = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter( + rstlist, self.state.memo.reporter + ) + try: + nested_parse_with_titles(self.state, rstlist, node) + finally: + self.state.memo.reporter = save + + +class QAPIDocDirective(NestedDirective): """Extract documentation from the specified QAPI .json file""" required_argument = 1
@@ -532,34 +566,6 @@ 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. - """ - # This is from kerneldoc.py -- it works around an API change in - # Sphinx between 1.6 and 1.7. Unlike kerneldoc.py, we use - # sphinx.util.nodes.nested_parse_with_titles() rather than the - # plain self.state.nested_parse(), and so we can drop the saving - # of title_styles and section_level that kerneldoc.py does, - # because nested_parse_with_titles() does that for us. - if USE_SSI: - with switch_source_input(self.state, rstlist): - nested_parse_with_titles(self.state, rstlist, node) - else: - save = self.state.memo.reporter - self.state.memo.reporter = AutodocReporter( - rstlist, self.state.memo.reporter - ) - try: - nested_parse_with_titles(self.state, rstlist, node) - finally: - self.state.memo.reporter = save - def setup(app): """Register qapi-doc directive with Sphinx"""
Signature · 1 line
2.45.0
Re: [PATCH 1/8] docs/qapidoc: factor out do_parse()
Quoted 4 lines · John Snow
Factor out the compatibility parser helper into a base class, so it can be shared by other directives.
Signed-off-by John Snow <[email protected]>
R-by stands.
Re: [PATCH 1/8] docs/qapidoc: factor out do_parse()
Quoted 9 lines · Markus Armbruster
Quoted 4 lines · John Snow
Factor out the compatibility parser helper into a base class, so it can be shared by other directives.
Signed-off-by John Snow <[email protected]>R-by stands.
Assuming true even if I rebase on top of the 3.x patches and do_parse() becomes quite a bit more trivial?
--js
Quoted 1 line
Re: [PATCH 1/8] docs/qapidoc: factor out do_parse()
Quoted 7 lines · John Snow
Quoted 5 lines · Markus Armbruster
Quoted 3 lines · John Snow
Factor out the compatibility parser helper into a base class, so it can be shared by other directives.
Quoted 6 lines
Quoted 3 lines
Quoted 1 line
Signed-off-by John Snow <[email protected]>R-by stands.
Assuming true even if I rebase on top of the 3.x patches and
do_parse()becomes quite a bit more trivial?
If you think the changes don't warrant a fresh review, keep my R-by. You may get one anyway ;)
PATCH 2/8 docs/qapidoc: create qmp-example directive
In reply to John SnowThis is a directive that creates a syntactic sugar for creating "Example" boxes very similar to the ones already used in the bitmaps.rst document, please see e.g.
https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-add
In its simplest form, when a custom title is not needed or wanted, and the example body is *solely* a QMP example:
```
.. qmp-example::
{body}
```is syntactic sugar for:
```
.. admonition:: Example:
.. code-block:: QMP
{body}
```When a custom, plaintext title that describes the example is desired, this form:
```
.. qmp-example::
:title: Defrobnification
{body}
```Is syntactic sugar for:
```
.. admonition:: Example: Defrobnification
.. code-block:: QMP
{body}
```Lastly, when Examples are multi-step processes that require non-QMP exposition, have lengthy titles, or otherwise involve prose with rST markup (lists, cross-references, etc), the most complex form:
```
.. qmp-example::
:annotated:
This example shows how to use `foo-command`::
{body}
For more information, please see `frobnozz`.
```Is desugared to:
```
.. admonition:: Example:
This example shows how to use `foo-command`::
{body}
For more information, please see `frobnozz`.
```Note that :annotated: and :title: options can be combined together, if desired.
The primary benefit here being documentation source consistently using the same directive for all forms of examples to ensure consistent visual styling, and ensuring all relevant prose is visually grouped alongside the code literal block.
Note that as of this commit, the code-block rST syntax "::" does not apply QMP highlighting; you would need to use ".. code-block:: QMP". The very next commit changes this behavior to assume all "::" code blocks within this directive are QMP blocks.
--- docs/sphinx/qapidoc.py | 55 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+)
docs/sphinx/qapidoc.py +55 -0
@@ -27,6 +27,7 @@ import os import re import textwrap +from typing import List from docutils import nodes from docutils.parsers.rst import Directive, directives
@@ -36,6 +37,7 @@ from qapi.schema import QAPISchema import sphinx +from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util.nodes import nested_parse_with_titles
@@ -567,10 +569,63 @@ def run(self): raise ExtensionError(str(err)) from err +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 instead. 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 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]: + content_node: nodes.Element = nodes.section() + self.do_parse(self.content, content_node) + 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__,
Signature · 1 line
2.45.0
Re: [PATCH 2/8] docs/qapidoc: create qmp-example directive
Quoted 79 lines · John Snow
This is a directive that creates a syntactic sugar for creating "Example" boxes very similar to the ones already used in the
bitmaps.rstdocument, please see e.g.
https://www.qemu.org/docs/master/interop/bitmaps.html#creation-block-dirty-bitmap-addIn its simplest form, when a custom title is not needed or wanted, and the example body is *solely* a QMP example:
``` .. qmp-example:: {body} ```is syntactic sugar for:
``` .. admonition:: Example: .. code-block:: QMP {body} ```When a custom, plaintext title that describes the example is desired, this form:
``` .. qmp-example:: :title: Defrobnification {body} ```Is syntactic sugar for:
``` .. admonition:: Example: Defrobnification .. code-block:: QMP {body} ```Lastly, when Examples are multi-step processes that require non-QMP exposition, have lengthy titles, or otherwise involve prose with rST markup (lists, cross-references, etc), the most complex form:
``` .. qmp-example:: :annotated: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ```Is desugared to:
``` .. admonition:: Example: This example shows how to use `foo-command`:: {body} For more information, please see `frobnozz`. ```Note that :annotated: and :title: options can be combined together, if desired.
The primary benefit here being documentation source consistently using the same directive for all forms of examples to ensure consistent visual styling, and ensuring all relevant prose is visually grouped alongside the code literal block.
Quoted 6 lines
Note that as of this commit, the code-block rST syntax "::" does not apply QMP highlighting; you would need to use ".. code-block:: QMP". The very next commit changes this behavior to assume all "::" code blocks within this directive are QMP blocks.
Signed-off-by John Snow <[email protected]>
PATCH 3/8 docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
In reply to John SnowFor any code literal blocks inside of a qmp-example directive, apply and enforce the QMP lexer/highlighter to those blocks.
This way, you won't need to write:
```
.. qmp-example::
:annotated:
Blah blah
.. code-block:: QMP
-> { "lorem": "ipsum" }
```But instead, simply:
```
.. qmp-example::
:annotated:
Blah blah::
-> { "lorem": "ipsum" }
```Once the directive block is exited, whatever the previous default highlight language was will be restored; localizing the forced QMP lexing to exclusively this directive.
Note, if the default language is *already* QMP, this directive will not generate and restore redundant highlight configuration nodes. We may well decide that the default language ought to be QMP for any QAPI reference pages, but this way the directive behaves consistently no matter where it is used.
--- docs/sphinx/qapidoc.py | 53 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 49 insertions(+), 4 deletions(-)
docs/sphinx/qapidoc.py +49 -4
@@ -26,6 +26,7 @@ import os import re +import sys import textwrap from typing import List
@@ -37,6 +38,7 @@ from qapi.schema import QAPISchema import sphinx +from sphinx import addnodes from sphinx.directives.code import CodeBlock from sphinx.errors import ExtensionError from sphinx.util.nodes import nested_parse_with_titles
@@ -574,10 +576,10 @@ 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 instead. 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. + 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.
@@ -591,6 +593,33 @@ class QMPExample(CodeBlock, NestedDirective): "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:
@@ -605,8 +634,24 @@ def admonition_wrap(self, *content) -> List[nodes.Node]: 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]:
Signature · 1 line
2.45.0
Re: [PATCH 3/8] docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
Quoted 31 lines · John Snow
For any code literal blocks inside of a qmp-example directive, apply and enforce the QMP lexer/highlighter to those blocks.
This way, you won't need to write:
``` .. qmp-example:: :annotated: Blah blah .. code-block:: QMP -> { "lorem": "ipsum" } ```But instead, simply:
``` .. qmp-example:: :annotated: Blah blah:: -> { "lorem": "ipsum" } ```Once the directive block is exited, whatever the previous default highlight language was will be restored; localizing the forced QMP lexing to exclusively this directive.
Quoted 7 lines
Note, if the default language is *already* QMP, this directive will not generate and restore redundant highlight configuration nodes. We may well decide that the default language ought to be QMP for any QAPI reference pages, but this way the directive behaves consistently no matter where it is used.
Signed-off-by John Snow <[email protected]>
Sadly, the previous patch didn't add tests, so this patch's effect isn't as easy to observe as it could be.
Re: [PATCH 3/8] docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
Quoted 39 lines · Markus Armbruster
Quoted 37 lines · John Snow
For any code literal blocks inside of a qmp-example directive, apply and enforce the QMP lexer/highlighter to those blocks.
This way, you won't need to write:
``` .. qmp-example:: :annotated: Blah blah .. code-block:: QMP -> { "lorem": "ipsum" } ```But instead, simply:
``` .. qmp-example:: :annotated: Blah blah:: -> { "lorem": "ipsum" } ```Once the directive block is exited, whatever the previous default highlight language was will be restored; localizing the forced QMP lexing to exclusively this directive.
Note, if the default language is *already* QMP, this directive will not generate and restore redundant highlight configuration nodes. We may well decide that the default language ought to be QMP for any QAPI reference pages, but this way the directive behaves consistently no matter where it is used.
Quoted 5 lines
Quoted 1 line
Signed-off-by John Snow <[email protected]>Sadly, the previous patch didn't add tests, so this patch's effect isn't as easy to observe as it could be.
Sorry O:-)
In truth, I never intended it to *not* have this feature, but thought it was helpful to split out just the code responsible for this feature into its own patch so its soul could be independently judged to see if it was lighter than a feather.
(i.e., does the convenience justify the SLOC?)
Quoted 3 lines
PATCH 4/8 docs/sphinx: add CSS styling for qmp-example directive
In reply to John SnowFrom: Harmonie Snow <[email protected]>
Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks.
--- docs/sphinx-static/theme_overrides.css | 49 ++++++++++++++++++++++++++ 1 file changed, 49 insertions(+)
docs/sphinx-static/theme_overrides.css +49 -0
@@ -87,6 +87,55 @@ div[class^="highlight"] pre { 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
Signature · 1 line
2.45.0
Re: [PATCH 4/8] docs/sphinx: add CSS styling for qmp-example directive
Quoted 7 lines · John Snow
From: Harmonie Snow <[email protected]>
Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks.
Signed-off-by Harmonie Snow <[email protected]>Signed-off-by John Snow <[email protected]>
Same sadness as for the previous patch.
Re: [PATCH 4/8] docs/sphinx: add CSS styling for qmp-example directive
Quoted 4 lines · Markus Armbruster
Quoted 2 lines · John Snow
From: Harmonie Snow <[email protected]>
Quoted 8 lines
Quoted 5 lines
Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks.
Signed-off-by Harmonie Snow <[email protected]>Signed-off-by John Snow <[email protected]>Same sadness as for the previous patch.
Should we do anything about that? In the long run, I don't expect anyone will actually need to care about what this directive looked like in some intermediate state before we ever used it. If you want to evaluate the directive in the in-between states, I recommend modifying a document and seeing what it does; but I didn't really intend for anyone to really see it that way.
(Isn't it a bit overboard to write unit tests for intermediate tree states...?)
Quoted 4 lines
Re: [PATCH 4/8] docs/sphinx: add CSS styling for qmp-example directive
Quoted 22 lines · John Snow
Quoted 4 lines · Markus Armbruster
Quoted 2 lines · John Snow
From: Harmonie Snow <[email protected]>
Quoted 8 lines
Quoted 5 lines
Add CSS styling for qmp-example directives to increase readability and consistently style all example blocks.
Signed-off-by Harmonie Snow <[email protected]>Signed-off-by John Snow <[email protected]>Same sadness as for the previous patch.
Should we do anything about that? In the long run, I don't expect anyone will actually need to care about what this directive looked like in some intermediate state before we ever used it. If you want to evaluate the directive in the in-between states, I recommend modifying a document and seeing what it does; but I didn't really intend for anyone to really see it that way.
Quoted 2 lines
(Isn't it a bit overboard to write unit tests for intermediate tree states...?)
I'm not asking for temporary tests, I just wonder why you delay permanent ones until "[PATCH 8/8] qapi: remove "Example" doc section".
No big deal, thus:
Quoted 1 line
Quoted 1 line
PATCH 5/8 qapi: convert "Example" sections without titles
In reply to John SnowUse the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.
See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.
--- qapi/acpi.json | 4 +-- qapi/block-core.json | 64 +++++++++++++++++++++------------------- qapi/block.json | 18 ++++++----- qapi/char.json | 24 +++++++++------ qapi/control.json | 8 ++--- qapi/dump.json | 8 ++--- qapi/machine-target.json | 2 +- qapi/machine.json | 38 ++++++++++++------------ qapi/migration.json | 58 ++++++++++++++++++------------------ qapi/misc-target.json | 22 +++++++------- qapi/misc.json | 32 ++++++++++---------- qapi/net.json | 20 +++++++------ qapi/pci.json | 2 +- qapi/qdev.json | 10 ++++--- qapi/qom.json | 8 ++--- qapi/replay.json | 8 ++--- qapi/rocker.json | 8 ++--- qapi/run-state.json | 30 +++++++++---------- qapi/tpm.json | 6 ++-- qapi/trace.json | 4 +-- qapi/transaction.json | 2 +- qapi/ui.json | 34 ++++++++++----------- qapi/vfio.json | 2 +- qapi/virtio.json | 2 +- qapi/yank.json | 4 +-- 25 files changed, 216 insertions(+), 202 deletions(-)
qapi/acpi.json +2 -2
@@ -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",
qapi/block-core.json +33 -31
256 lines not on this page · raw message
qapi/block.json +10 -8
@@ -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": {
@@ -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,
qapi/char.json +15 -9
@@ -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 },
qapi/control.json +4 -4
@@ -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": {} }
qapi/dump.json +4 -4
@@ -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":
qapi/machine-target.json +1 -1
@@ -475,7 +475,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "CPU_POLARIZATION_CHANGE", # "data": { "polarization": "horizontal" },
qapi/machine.json +19 -19
@@ -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": [
@@ -320,7 +320,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-uuid" } # <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
@@ -354,7 +354,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "system_reset" } # <- { "return": {} }
@@ -373,7 +373,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 +393,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 +444,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 +473,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-kvm" } # <- { "return": { "enabled": true, "present": true } }
@@ -842,7 +842,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "memsave", # "arguments": { "val": 10,
@@ -868,7 +868,7 @@ # # .. caution:: Errors were not reliably returned until 1.1. # -# Example: +# .. qmp-example:: # # -> { "execute": "pmemsave", # "arguments": { "val": 10,
@@ -929,7 +929,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memdev" } # <- { "return": [
@@ -1166,7 +1166,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-balloon" } # <- { "return": {
@@ -1190,7 +1190,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # <- { "event": "BALLOON_CHANGE", # "data": { "actual": 944766976 },
@@ -1232,7 +1232,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-hv-balloon-status-report" } # <- { "return": {
@@ -1253,7 +1253,7 @@ # # Since: 8.2 # -# Example: +# .. qmp-example:: # # <- { "event": "HV_BALLOON_STATUS_REPORT", # "data": { "committed": 816640000, "available": 3333054464 },
@@ -1285,7 +1285,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 +1564,7 @@ # # Since: 2.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-memory-devices" } # <- { "return": [ { "data":
@@ -1598,7 +1598,7 @@ # # Since: 5.1 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", # "data": { "id": "vm0", "size": 1073741824,
@@ -1856,7 +1856,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "dumpdtb" } # "arguments": { "filename": "fdt.dtb" } }
qapi/migration.json +29 -29
232 lines not on this page · raw message
qapi/misc-target.json +11 -11
@@ -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": { } }
qapi/misc.json +16 -16
@@ -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",
qapi/net.json +11 -9
@@ -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,7 @@ # switches. This can be useful when network bonds fail-over the # active slave. # -# Example: +# .. qmp-example:: # # -> { "execute": "announce-self", # "arguments": {
@@ -955,7 +955,7 @@ # # Since: 4.2 # -# Example: +# .. qmp-example:: # # <- { "event": "FAILOVER_NEGOTIATED", # "data": { "device-id": "net1" },
@@ -975,7 +975,7 @@ # # Since: 7.2 # -# Examples: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_CONNECTED", # "data": { "netdev-id": "netdev0",
@@ -983,6 +983,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 +1003,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # <- { "event": "NETDEV_STREAM_DISCONNECTED", # "data": {"netdev-id": "netdev0"},
qapi/pci.json +1 -1
@@ -182,7 +182,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-pci" } # <- { "return": [
qapi/qdev.json +6 -4
@@ -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",
qapi/qom.json +4 -4
@@ -59,7 +59,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-list", # "arguments": { "path": "/chardevs" } }
@@ -139,7 +139,7 @@ # # Since: 1.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "qom-set", # "arguments": { "path": "/machine",
@@ -1154,7 +1154,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-add", # "arguments": { "qom-type": "rng-random", "id": "rng1",
@@ -1176,7 +1176,7 @@ # # Since: 2.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "object-del", "arguments": { "id": "rng1" } } # <- { "return": {} }
qapi/replay.json +4 -4
@@ -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": {} }
qapi/rocker.json +4 -4
@@ -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" } }
qapi/run-state.json +15 -15
@@ -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" },
@@ -597,7 +597,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor",
qapi/tpm.json +3 -3
@@ -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":
qapi/trace.json +2 -2
@@ -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 } }
qapi/transaction.json +1 -1
@@ -244,7 +244,7 @@ # # Since: 1.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "transaction", # "arguments": { "actions": [
qapi/ui.json +17 -17
@@ -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" } }
@@ -330,7 +330,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-spice" } # <- { "return": {
@@ -379,7 +379,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_CONNECTED",
@@ -405,7 +405,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_INITIALIZED",
@@ -432,7 +432,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707}, # "event": "SPICE_DISCONNECTED",
@@ -453,7 +453,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172}, # "event": "SPICE_MIGRATE_COMPLETED" }
@@ -661,7 +661,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-vnc" } # <- { "return": {
@@ -726,7 +726,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_CONNECTED", # "data": {
@@ -753,7 +753,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_INITIALIZED", # "data": {
@@ -779,7 +779,7 @@ # # Since: 0.13 # -# Example: +# .. qmp-example:: # # <- { "event": "VNC_DISCONNECTED", # "data": {
@@ -827,7 +827,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "query-mice" } # <- { "return": [
@@ -1036,7 +1036,7 @@ # # Since: 1.3 # -# Example: +# .. qmp-example:: # # -> { "execute": "send-key", # "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
@@ -1615,7 +1615,7 @@ # # Since: 6.0 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-reload", # "arguments": { "type": "vnc", "tls-certs": true } }
@@ -1672,7 +1672,7 @@ # # Since: 7.1 # -# Example: +# .. qmp-example:: # # -> { "execute": "display-update", # "arguments": { "type": "vnc", "addresses":
@@ -1703,7 +1703,7 @@ # # Since: 0.14 # -# Example: +# .. qmp-example:: # # -> { "execute": "client_migrate_info", # "arguments": { "protocol": "spice",
qapi/vfio.json +1 -1
@@ -50,7 +50,7 @@ # # Since: 9.1 # -# Example: +# .. qmp-example:: # # <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 }, # "event": "VFIO_MIGRATION",
qapi/virtio.json +1 -1
@@ -34,7 +34,7 @@ # # Since: 7.2 # -# Example: +# .. qmp-example:: # # -> { "execute": "x-query-virtio" } # <- { "return": [
qapi/yank.json +2 -2
@@ -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": [
Signature · 1 line
2.45.0
Re: [PATCH 5/8] qapi: convert "Example" sections without titles
Quoted 13 lines · John Snow
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.Signed-off-by John Snow <[email protected]>
[...]
Quoted 4 lines
qapi/run-state.json +0
-0
[...]
qapi/run-state.json line 459
Quoted 9 lines
qapi/run-state.json +1
-1@@ -453,7 +453,7 @@ # # Since: 5.0 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" },
Trivial semantic conflict, we need
@@ -469,7 +469,7 @@
#
# Since: 9.1
#
-# Example:
+# .. qmp-example::
#
# <- { "event": "GUEST_PVSHUTDOWN",
# "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }
Quoted 9 lines
qapi/run-state.json +1
-1@@ -597,7 +597,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor",
[...]
Re: [PATCH 5/8] qapi: convert "Example" sections without titles
Quoted 25 lines · Markus Armbruster
Quoted 13 lines · John Snow
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.Signed-off-by John Snow <[email protected]>[...]
Quoted 4 lines
qapi/run-state.json +0
-0[...]
Quoted 12 lines
qapi/run-state.json line 459
Quoted 9 lines
qapi/run-state.json +1
-1@@ -453,7 +453,7 @@ # # Since: 5.0 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" },Trivial semantic conflict, we need
Caught on rebase late Fri, already fixed locally and will be in v2 (which I rebased on top of my sphinx 3.x patches, which change the do_parse() stuff too.)
Quoted 25 lines
@@ -469,7 +469,7 @@
#
# Since: 9.1
#
-# Example:
+# .. qmp-example::# # <- { "event": "GUEST_PVSHUTDOWN", # "timestamp": { "seconds": 1648245259, "microseconds": 893771 } }Quoted 9 lines
qapi/run-state.json +1
-1@@ -597,7 +597,7 @@ # # Since: 5.2 # -# Example: +# .. qmp-example:: # # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor",[...]
Markus Armbruster
Reviewed-byRe: [PATCH 5/8] qapi: convert "Example" sections without titles
Quoted 40 lines · John Snow
Quoted 25 lines · Markus Armbruster
Quoted 13 lines · John Snow
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a
detailed explanation of this custom directive syntax.See commit+3: "qapi: remove "Example" doc section" for a detailed
explanation of why.Signed-off-by John Snow <[email protected]>[...]
Quoted 4 lines
qapi/run-state.json +0
-0[...]
Quoted 12 lines
qapi/run-state.json line 459
Quoted 9 lines
qapi/run-state.json +1
-1@@ -453,7 +453,7 @@ # # Since: 5.0 # -# Example: +# .. qmp-example:: # # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" },Trivial semantic conflict, we need
Quoted 3 lines
Caught on rebase late Fri, already fixed locally and will be in v2 (which I rebased on top of my sphinx 3.x patches, which change the
do_parse()stuff too.)
With that fix
[...]
PATCH 6/8 qapi: convert "Example" sections with titles
In reply to John SnowWhen 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.
--- qapi/block-core.json | 24 ++++++++++++------------ qapi/block.json | 13 ++++++------- qapi/migration.json | 25 ++++++++++++++----------- qapi/qom.json | 8 ++++---- qapi/ui.json | 11 ++++++----- qapi/virtio.json | 19 ++++++++++--------- 6 files changed, 52 insertions(+), 48 deletions(-)
qapi/block-core.json +12 -12
@@ -5885,9 +5885,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": {
@@ -5901,7 +5900,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",
@@ -5937,16 +5937,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",
@@ -6022,16 +6022,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,
qapi/block.json +6 -7
@@ -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",
@@ -577,9 +577,8 @@ # "boundaries-write": [1000, 5000] } } # <- { "return": {} } # -# Example: -# -# Remove all latency histograms: +# .. qmp-example:: +# :title: Remove all latency histograms # # -> { "execute": "block-latency-histogram-set", # "arguments": { "id": "drive0" } }
qapi/migration.json +14 -11
@@ -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" } # <- {
@@ -2131,15 +2134,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,
qapi/qom.json +4 -4
@@ -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",
qapi/ui.json +6 -5
@@ -1272,9 +1272,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 +1287,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 +1300,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": [
qapi/virtio.json +10 -9
@@ -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",
Signature · 1 line
2.45.0
Re: [PATCH 6/8] qapi: convert "Example" sections with titles
Quoted 11 lines · John Snow
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.
Quoted 7 lines
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 <[email protected]>
PATCH 7/8 qapi: convert "Example" sections with longer prose
In reply to John SnowThese 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.
--- qapi/block.json | 26 ++++++++++++++++---------- qapi/machine.json | 30 ++++++++++++++++++++---------- qapi/migration.json | 7 +++++-- qapi/virtio.json | 24 ++++++++++++++++++------ 4 files changed, 59 insertions(+), 28 deletions(-)
qapi/block.json +16 -10
@@ -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",
qapi/machine.json +20 -10
@@ -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'} }
qapi/migration.json +5 -2
@@ -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"} }
qapi/virtio.json +18 -6
@@ -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",
Signature · 1 line
2.45.0
Re: [PATCH 7/8] qapi: convert "Example" sections with longer prose
Quoted 69 lines · John Snow
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 <[email protected]>--- qapi/block.json | 26 ++++++++++++++++---------- qapi/machine.json | 30 ++++++++++++++++++++---------- qapi/migration.json | 7 +++++-- qapi/virtio.json | 24 ++++++++++++++++++------ 4 files changed, 59 insertions(+), 28 deletions(-)qapi/block.json +10
-9@@ -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)
qapi/block.json line 581
Quoted 10 lines
qapi/block.json +6
-1-# 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.
[...]
Re: [PATCH 7/8] qapi: convert "Example" sections with longer prose
Quoted 93 lines · Markus Armbruster
Quoted 69 lines · John Snow
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 <[email protected]>--- qapi/block.json | 26 ++++++++++++++++---------- qapi/machine.json | 30 ++++++++++++++++++++---------- qapi/migration.json | 7 +++++-- qapi/virtio.json | 24 ++++++++++++++++++------ 4 files changed, 59 insertions(+), 28 deletions(-)qapi/block.json +10
-9@@ -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)qapi/block.json line 581
Quoted 10 lines
qapi/block.json +6
-1-# 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": {} } ##
Quoted 2 lines
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.
Quoted 6 lines
[...]
Reviewed-by Markus Armbruster <[email protected]>
PATCH 8/8 qapi: remove "Example" doc section
In reply to John SnowFully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired.
Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion patch, this patch (and those
preceding) may change the rendering order for Examples in the current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order.
--- docs/devel/qapi-code-gen.rst | 58 ++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-)
docs/devel/qapi-code-gen.rst +49 -9
@@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ 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 @@ line "Features:", like this:: # @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 @@ detailing a relevant error condition. For example:: 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 at all (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 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats',
scripts/qapi/parser.py +9 -1
@@ -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:
tests/qapi-schema/doc-good.json +12 -7
@@ -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',
tests/qapi-schema/doc-good.out +18 -8
@@ -184,13 +184,21 @@ frobnicate - 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 @@ If you're bored enough to read this, go see a video of boxed cats 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=
tests/qapi-schema/doc-good.txt +10 -13
@@ -217,17 +217,16 @@ Notes: 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 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example" - -> in - - <- out + <- "has no title" "EVT_BOXED" (Event)
Signature · 1 line
2.45.0
Re: [PATCH 8/8] qapi: remove "Example" doc section
Quoted 44 lines · John Snow
Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired.
Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive.
Why?
----This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.)
Quoted 7 lines
4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion patch,
Commit d461c279737 (qapi: convert "Note" sections to plain rST).
Quoted 2 lines
this patch (and those
preceding) may change the rendering order for Examples in the
The three preceding ones, to be precise.
Quoted 2 lines
current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order.
Conversions from "Example" section to plain reST may change order. This patch converts a test, and the preceding three convert the real uses.
Does any of the patches actually change order?
Quoted 34 lines
Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-code-gen.rst | 58 ++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-)docs/devel/qapi-code-gen.rst +3
-3@@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ 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 @@ line "Features:", like this:: # @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::
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1023
Quoted 8 lines
docs/devel/qapi-code-gen.rst +1
-4@@ -1020,13 +1020,53 @@ detailing a relevant error condition. For example:: 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 at all (they are for developers, not
Drop "at all"?
Quoted 97 lines
docs/devel/qapi-code-gen.rst +45
-2+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 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats',scripts/qapi/parser.py +9
-1@@ -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:tests/qapi-schema/doc-good.json +0
-0@@ -172,12 +172,17 @@ #
tests/qapi-schema/doc-good.json line 179
Quoted 10 lines
tests/qapi-schema/doc-good.json +4
-3# Duis aute irure dolor # -# Example: +# .. qmp-example:: +# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out"
Heh, trickery to make the text right of -> and <- JSON.
Quoted 12 lines
tests/qapi-schema/doc-good.json +5
-1# -# 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
tests/qapi-schema/doc-good.json line 211
Quoted 10 lines
tests/qapi-schema/doc-good.json +3
-3# @cmd-feat2: another feature # -# Example: +# .. qmp-example:: # -# -> in +# -> "this example" # -# <- out +# <- "has no title"
Same trickery.
Quoted 96 lines
tests/qapi-schema/doc-good.json +0
-0## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object',tests/qapi-schema/doc-good.out +18
-8@@ -184,13 +184,21 @@ frobnicate - 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 @@ If you're bored enough to read this, go see a video of boxed cats 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=tests/qapi-schema/doc-good.txt +10
-13@@ -217,17 +217,16 @@ Notes: 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 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example" - -> in - - <- out + <- "has no title" "EVT_BOXED" (Event)
Re: [PATCH 8/8] qapi: remove "Example" doc section
Quoted 49 lines · Markus Armbruster
Quoted 47 lines · John Snow
Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired.
Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive.
Why?
----This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator.
Quoted 7 lines
Quoted 4 lines
(i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion patch,
Commit
d461c279737(qapi: convert "Note" sections to plain rST).
Didn't have a stable commit ID at the time, will work it in if/when the notes patches hit main.
Quoted 6 lines
Quoted 3 lines
this patch (and those
preceding) may change the rendering order for Examples in theThe three preceding ones, to be precise.
Quoted 8 lines
Quoted 2 lines
current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order.
Conversions from "Example" section to plain reST may change order. This patch converts a test, and the preceding three convert the real uses.
Does any of the patches actually change order?
I do not actually know ...! It has the *potential* in the same exact way that the notes patch did, but I don't actually know if it *did*. My hunch is "no" because there's only one intermediate section we identified with the notes series, but I didn't exhaustively prove it. That's why I used the "may" weasel wording.
Quoted 39 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For
Quoted 35 lines
Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-code-gen.rst | 58 ++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-)docs/devel/qapi-code-gen.rst +3
-3@@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ 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 @@ line "Features:", like this:: # @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 @@ detailing a relevant error condition. Forexample::
Quoted 3 lines
docs/devel/qapi-code-gen.rst +0
-0A "Since: x.y.z" tagged section lists the release that introduced the definition.
Quoted 8 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1023
Quoted 5 lines
docs/devel/qapi-code-gen.rst +1
-4-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 at all (they are for developers, notDrop "at all"?
Sure.
Quoted 17 lines
Quoted 17 lines
docs/devel/qapi-code-gen.rst +16
-0+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
Quoted 9 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1047
Quoted 8 lines
docs/devel/qapi-code-gen.rst +8
-0+ # + # -> { "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.
Telling on myself: you can use .. code-block:: QMP too, but I figured recommending "::" was shorter and sweeter. There are lots of minutiae here for people who haven't spent a long time reading and writing rST, so I tried to keep it short.
Quoted 82 lines
Quoted 44 lines
docs/devel/qapi-code-gen.rst +21
-2+ +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 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats',scripts/qapi/parser.py +0
-0scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 554
Quoted 2 lines
scripts/qapi/parser.py +0
-0@@ -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 sectionheading.
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 572
Quoted 13 lines
scripts/qapi/parser.py +4
-1- # 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 nolonger "
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 573
Quoted 1 line
scripts/qapi/parser.py +1
-0+ "supported. Please use the '..qmp-example::' "
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 574
Quoted 1 line
scripts/qapi/parser.py +1
-0+ "directive, or other suitable markupinstead."
Review
Quoted 7 lines
scripts/qapi/parser.py +3
-0+ ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info, match.group(1)) text = line[match.end():] if text:(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.jsonQuoted 9 lines
index
107123f8a8d..c71d65cd51f100644tests/qapi-schema/doc-good.json +1
-1@@ -172,12 +172,17 @@ # # Duis aute irure dolor # -# Example: +# .. qmp-example::
Quoted 9 lines
tests/qapi-schema/doc-good.json line 179
Quoted 6 lines
tests/qapi-schema/doc-good.json +3
-2+# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out"Heh, trickery to make the text right of -> and <- JSON.
O:-)
It's maybe *slightly* bad form, but it does help illustrate how the new directive is transformed when using text output modes in the test suite, so I kept it. The new directive will simply not allow malformed JSON, so this seemed like the simplest way to cheese that.
Quoted 11 lines
tests/qapi-schema/doc-good.json line 187
Quoted 10 lines
tests/qapi-schema/doc-good.json +5
-1# -# Examples: +# Examples:: +# +# - Not a QMP code block +# - Merely a preformatted code block literal +# It isn't even an rST list. # - *verbatim* # - {braces}
(And here, we test the use of non-QMP code block literals, esp. after the qmp-example directive, proving that language settings have been restored to defaults.)
Quoted 7 lines
Quoted 7 lines
tests/qapi-schema/doc-good.json +1
-1#@@ -199,11 +204,11 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. qmp-example::
Quoted 9 lines
tests/qapi-schema/doc-good.json line 211
Quoted 6 lines
tests/qapi-schema/doc-good.json +2
-2# -# -> in +# -> "this example" # -# <- out +# <- "has no title"Same trickery.
Do you want that changed ... ?
Quoted 55 lines
Review
Quoted 5 lines
tests/qapi-schema/doc-good.json +0
-0## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object',(quoted diff) +0
-0b/tests/qapi-schema/doc-good.out
tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a
Quoted 31 lines
index
bd876b6542d..eee18cd436a100644tests/qapi-schema/doc-good.out +13
-5@@ -184,13 +184,21 @@ frobnicate - 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 @@ If you're bored enough to read this, go see avideo of boxed cats
Review
Quoted 16 lines
tests/qapi-schema/doc-good.out +5
-3a feature feature=cmd-feat2 another feature - section=Example - -> in + section=None +.. qmp-example:: - <- out + -> "this example" + + <- "has no title" doc symbol=EVT_BOXED body=(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.txt
Quoted 9 lines
tests/qapi-schema/doc-good.txt Notes: · line 220
Quoted 8 lines
index
30d457e5488..cb37db606a6100644tests/qapi-schema/doc-good.txt +1
-0@@ -217,17 +217,16 @@ Notes: Duis aute irure dolor +Example: Ideal fast-food burger situation:
No comment on the american making fast food burger jokes? :-(
Quoted 30 lines
Quoted 30 lines
tests/qapi-schema/doc-good.txt +8
-10-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 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example"
Quoted 8 lines
tests/qapi-schema/doc-good.txt Features · line 270
Quoted 7 lines
tests/qapi-schema/doc-good.txt +1
-3- -> in - - <- out + <- "has no title" "EVT_BOXED" (Event)
Does this adequately resolve your qualms about .txt rendering for examples?
--js
Re: [PATCH 8/8] qapi: remove "Example" doc section
Quoted 54 lines · John Snow
Quoted 52 lines · Markus Armbruster
Quoted 50 lines · John Snow
Fully eliminate the "Example" sections in QAPI doc blocks now that they have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::" will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into the title bar for the example. The ":annotated:" option can be used to write arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired.
Other choices available are ".. code-block:: QMP" which will not create an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive.
Why?
----This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.)
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
NOTE: As with the "Notes" conversion patch,
Commit
d461c279737(qapi: convert "Note" sections to plain rST).Didn't have a stable commit ID at the time, will work it in if/when the notes patches hit main.
They have.
Quoted 11 lines
Quoted 11 lines
Quoted 2 lines
this patch (and those
preceding) may change the rendering order for Examples in theThe three preceding ones, to be precise.
Quoted 2 lines
current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order.
Conversions from "Example" section to plain reST may change order. This patch converts a test, and the preceding three convert the real uses.
Quoted 7 lines
Quoted 1 line
Does any of the patches actually change order?
I do not actually know ...! It has the *potential* in the same exact way that the notes patch did, but I don't actually know if it *did*. My hunch is "no" because there's only one intermediate section we identified with the notes series, but I didn't exhaustively prove it. That's why I used the "may" weasel wording.
Alright, I checked.
In documentation of command announce-self, the example moves from after the arguments to before. Unwanted change.
I can keep it in place if I insert a TODO before the example like this:
diff --git a/qapi/net.json b/qapi/net.json
index 9a723e56b5..50bfd5b681 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -930,6 +930,8 @@
# switches. This can be useful when network bonds fail-over the
# active slave.
#
+# TODO: This line is a hack to separate the example from the body
+#
# .. qmp-example::
#
# -> { "execute": "announce-self",I had to delete the .doctrees cache to make sphinx-build generate corrected output.
Quoted 77 lines
Quoted 38 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For
Quoted 34 lines
Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-code-gen.rst | 58 ++++++++++++++++++++++++++++----- scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-)docs/devel/qapi-code-gen.rst +3
-3@@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ 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 @@ line "Features:", like this:: # @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 @@ detailing a relevant error condition. Forexample::
Quoted 3 lines
docs/devel/qapi-code-gen.rst +0
-0A "Since: x.y.z" tagged section lists the release that introduced the definition.Quoted 8 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1023
Quoted 5 lines
docs/devel/qapi-code-gen.rst +1
-4-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 at all (they are for developers, notDrop "at all"?
Sure.
Quoted 17 lines
Quoted 17 lines
docs/devel/qapi-code-gen.rst +16
-0+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-blockQuoted 9 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1047
Quoted 8 lines
docs/devel/qapi-code-gen.rst +8
-0+ # + # -> { "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.
Quoted 4 lines
Telling on myself: you can use .. code-block:: QMP too, but I figured recommending "::" was shorter and sweeter. There are lots of minutiae here for people who haven't spent a long time reading and writing rST, so I tried to keep it short.
Makes sense.
Quoted 87 lines
Quoted 77 lines
Quoted 77 lines
docs/devel/qapi-code-gen.rst +21
-2+ +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 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # } ## { 'command': 'query-blockstats',scripts/qapi/parser.py +9
-1@@ -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:tests/qapi-schema/doc-good.json +1
-1@@ -172,12 +172,17 @@ # # Duis aute irure dolor # -# Example: +# .. qmp-example::Quoted 9 lines
tests/qapi-schema/doc-good.json line 179
Quoted 6 lines
tests/qapi-schema/doc-good.json +3
-2+# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out"Heh, trickery to make the text right of -> and <- JSON.
Quoted 6 lines
O:-)
It's maybe *slightly* bad form, but it does help illustrate how the new directive is transformed when using text output modes in the test suite, so I kept it. The new directive will simply not allow malformed JSON, so this seemed like the simplest way to cheese that.
I figure an alternative would be a more flexible "...".
Two hunks up, you dumb one down:
- # Example:
+ # .. qmp-example::
#
# -> { "execute": "query-blockstats" }
# <- {
- # ... lots of output ...
+ # ...
# }
If qmp_lexer.py understood this more verbose ellipsis, we could use something like
# -> ... input ...
# <- ... output ...Worth the bother? Certainly not just for tests. Maybe for nicer examples in real documentation? Up to you!
Quoted 11 lines
Quoted 10 lines
tests/qapi-schema/doc-good.json line 187
Quoted 9 lines
tests/qapi-schema/doc-good.json +5
-1# -# Examples: +# Examples:: +# +# - Not a QMP code block +# - Merely a preformatted code block literal +# It isn't even an rST list. # - *verbatim* # - {braces}
Quoted 3 lines
(And here, we test the use of non-QMP code block literals, esp. after the qmp-example directive, proving that language settings have been restored to defaults.)
Appreciated.
Quoted 17 lines
Quoted 7 lines
Quoted 7 lines
tests/qapi-schema/doc-good.json +1
-1#@@ -199,11 +204,11 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. qmp-example::Quoted 9 lines
tests/qapi-schema/doc-good.json line 211
Quoted 6 lines
tests/qapi-schema/doc-good.json +2
-2# -# -> in +# -> "this example" # -# <- out +# <- "has no title"Same trickery.
Quoted 1 line
Do you want that changed ... ?
It's just a test, good enough.
Quoted 56 lines
Quoted 56 lines
Quoted 56 lines
tests/qapi-schema/doc-good.json +0
-0## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object',tests/qapi-schema/doc-good.out +18
-8@@ -184,13 +184,21 @@ frobnicate - 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 @@ If you're bored enough to read this, go see a video of boxed cats 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=tests/qapi-schema/doc-good.txt +0
-0@@ -217,17 +217,16 @@ Notes:
Quoted 6 lines
Quoted 4 lines
tests/qapi-schema/doc-good.txt Notes: · line 220
Quoted 3 lines
tests/qapi-schema/doc-good.txt +1
-0Duis aute irure dolor +Example: Ideal fast-food burger situation:No comment on the american making fast food burger jokes? :-(
I chuckled, but no witticism came to me, so...
Quoted 37 lines
Quoted 37 lines
Quoted 37 lines
tests/qapi-schema/doc-good.txt +9
-13-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 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example" - -> in - - <- out + <- "has no title"
Quoted 4 lines
Quoted 2 lines
tests/qapi-schema/doc-good.txt Features · line 270
Quoted 1 line
tests/qapi-schema/doc-good.txt +0
-0"EVT_BOXED" (Event)Does this adequately resolve your qualms about .txt rendering for examples?
I think you mean my "Rendering to text now loses the "Example" heading" on "[PATCH 13/13] qapi: convert "Example" sections to rST". The diff above demonstrates it's no longer lost.
There's a tiny issue you may or may not want to address: an example isn't always separated by a blank line. To reproduce, add my TODO hack to announce-self, and examine qemu-qmp-ref.txt:
"announce-self" (Command)
-------------------------
Trigger generation of broadcast RARP frames to update network switches. This can be useful when network bonds fail-over the active slave.
Arguments
~~~~~~~~~
--> The members of "AnnounceParameters"
--> Example::
-> { "execute": "announce-self",
"arguments": {
"initial": 50, "max": 550, "rounds": 10, "step": 50,
"interfaces": ["vn2", "vn3"], "id": "bob" } }
<- { "return": {} }Re: [PATCH 8/8] qapi: remove "Example" doc section
Quoted 329 lines · Markus Armbruster
Quoted 1 line · John Snow
On Tue, Jul 9, 2024 at 6:52 AM Markus Armbruster <[email protected]>
Quoted 4 lines · wrote:
Quoted 4 lines
Quoted 1 line · John Snow
Fully eliminate the "Example" sections in QAPI doc blocks now that
they
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
have all been converted to arbitrary rST syntax using the ".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------The old "Example:" or "Examples:" section syntax is now caught as an error, but "Example::" is stil permitted as explicit rST syntax for an un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with
"::"
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly recommended that documentation authors use the ".. qmp-example::" directive for consistent visual formatting in rendered HTML docs. The ":title:" directive option may be used to add extra information into
the
Quoted 1 line
Quoted 1 line
Quoted 1 line
title bar for the example. The ":annotated:" option can be used to
write
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
arbitrary rST instead, with nested "::" blocks applying QMP formatting where desired.
Other choices available are ".. code-block:: QMP" which will not
create
Quoted 12 lines
Quoted 12 lines
Quoted 12 lines
an "Example:" box, or the short-form "::" code-block syntax which will not apply QMP highlighting when used outside of the qmp-example directive.
Why?
----This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing explanatory paragraphs and code blocks however desired.
Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly,
not
Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
that it's valid under the JSON or QMP grammars. It will catch most small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to sacrifice exposition for having lexically valid examples.)
Quoted 7 lines
Quoted 4 lines
Quoted 1 line
NOTE: As with the "Notes" conversion patch,
Commit
d461c279737(qapi: convert "Note" sections to plain rST).Didn't have a stable commit ID at the time, will work it in if/when the notes patches hit main.
They have.
Quoted 11 lines
Quoted 11 lines
Quoted 2 lines
this patch (and those
preceding) may change the rendering order for Examples in theThe three preceding ones, to be precise.
Quoted 2 lines
current generator. The forthcoming qapidoc rewrite will fix this by always generating documentation in source order.
Conversions from "Example" section to plain reST may change order. This patch converts a test, and the preceding three convert the real uses.
Quoted 6 lines
Quoted 1 line
Does any of the patches actually change order?
I do not actually know ...! It has the *potential* in the same exact way that the notes patch did, but I don't actually know if it *did*. My hunch is "no" because there's only one intermediate section we identified with the notes series, but I didn't exhaustively prove it. That's why I used
the
Quoted 1 line
"may" weasel wording.
Alright, I checked.
In documentation of command announce-self, the example moves from after the arguments to before. Unwanted change.
I can keep it in place if I insert a TODO before the example like this:
diff --git a/qapi/net.json b/qapi/net.json index 9a723e56b5..50bfd5b681 100644 --- a/qapi/net.json +++ b/qapi/net.json @@ -930,6 +930,8 @@ # switches. This can be useful when network bonds fail-over the # active slave. # +# TODO: This line is a hack to separate the example from the body +# # .. qmp-example:: # # -> { "execute": "announce-self",I had to delete the .doctrees cache to make sphinx-build generate corrected output.
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Signed-off-by John Snow <[email protected]>--- docs/devel/qapi-code-gen.rst | 58++++++++++++++++++++++++++++-----
Quoted 7 lines
Quoted 7 lines
Review
Quoted 7 lines
scripts/qapi/parser.py | 10 +++++- tests/qapi-schema/doc-good.json | 19 +++++++---- tests/qapi-schema/doc-good.out | 26 ++++++++++----- tests/qapi-schema/doc-good.txt | 23 ++++++------- 5 files changed, 98 insertions(+), 38 deletions(-)(quoted diff) +0
-0
b/docs/devel/qapi-code-gen.rstQuoted 15 lines
Quoted 15 lines
Quoted 15 lines
index
ae97b335cbf..2e10a3cbd69100644docs/devel/qapi-code-gen.rst +1
-1@@ -899,7 +899,7 @@ Documentation markup ~~~~~~~~~~~~~~~~~~~~ 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 @@ line "Features:", like this:: # @feature: Description textQuoted 4 lines
Quoted 4 lines
docs/devel/qapi-code-gen.rst line "Features:", like this::
Quoted 4 lines
docs/devel/qapi-code-gen.rst +1
-2A 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 endswith
Quoted 18 lines
Quoted 9 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For
Quoted 5 lines
docs/devel/qapi-code-gen.rst +1
-0+the start of a new section. The second and subsequent lines of tagged sections must be indented like this::@@ -1020,13 +1020,53 @@ detailing a relevant error condition. Forexample::
Quoted 3 lines
docs/devel/qapi-code-gen.rst +0
-0A "Since: x.y.z" tagged section lists the release that introduced the definition.Quoted 8 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1023
Quoted 5 lines
docs/devel/qapi-code-gen.rst +1
-4-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 at all (they are for developers, notDrop "at all"?
Quoted 5 lines
Sure.
Quoted 2 lines
Quoted 2 lines
docs/devel/qapi-code-gen.rst +1
-0+users of QMP). In other sections, the text is formatted, and rSTmarkup
Quoted 5 lines
Quoted 5 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example::
Quoted 5 lines
docs/devel/qapi-code-gen.rst +5
-0+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 additionalserver
Quoted 1 line
Quoted 1 line
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For · line 1030
Quoted 1 line
docs/devel/qapi-code-gen.rst +1
-0+directionality indicators (``->`` and ``<-``), and elisions(``...``).
Quoted 2 lines
Quoted 2 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For · line 1032
Quoted 2 lines
docs/devel/qapi-code-gen.rst +2
-0+ +Optionally, a plaintext title may be provided by using the``:title:``
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
docs/devel/qapi-code-gen.rst +4
-0+directive option. If the title is omitted, the example title will +default to "Example:". + +A simple QMP example::Quoted 8 lines
Quoted 8 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example::
Quoted 8 lines
docs/devel/qapi-code-gen.rst +8
-0+ + # .. qmp-example:: + # :title: Using query-block + # + # -> { "execute": "query-block" } + # <- { ... } + +More complex or multi-step examples where exposition is neededbefore or
Quoted 2 lines
Quoted 2 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For · line 1046
Quoted 2 lines
docs/devel/qapi-code-gen.rst +2
-0+between QMP code blocks can be created by using the ``:annotated:`` +directive option. When using this option, nested QMP code blocksmust be
Quoted 5 lines
Quoted 2 lines
docs/devel/qapi-code-gen.rst detailing a relevant error condition. For example:: · line 1047
Quoted 1 line
docs/devel/qapi-code-gen.rst +1
-0+entered explicitly with rST's ``::`` syntax.Telling on myself: you can use .. code-block:: QMP too, but I figured recommending "::" was shorter and sweeter. There are lots of minutiae
here
Quoted 2 lines
for people who haven't spent a long time reading and writing rST, so I tried to keep it short.
Makes sense.
Quoted 37 lines
Quoted 37 lines
Quoted 37 lines
docs/devel/qapi-code-gen.rst +21
-2+ +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 @@ For example:: # # Since: 0.14 # - # Example: + # .. qmp-example:: # # -> { "execute": "query-blockstats" } # <- { - # ... lots of output ... + # ... # }Quoted 8 lines
Quoted 8 lines
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 553
Quoted 8 lines
docs/devel/qapi-code-gen.rst +0
-0## { 'command': 'query-blockstats',scripts/qapi/parser.py +0
-0@@ -553,7 +553,7 @@ def get_doc(self) -> 'QAPIDoc': # Note: "sections" with two colons are leftalone as
Quoted 1 line
Quoted 1 line
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 554
Quoted 1 line
scripts/qapi/parser.py +0
-0# rST markup and not interpreted as a sectionheading.
Quoted 3 lines
Quoted 3 lines
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 555
Quoted 3 lines
scripts/qapi/parser.py +1
-1- # TODO: Remove this error sometime in 2025 or so + # TODO: Remove these errors sometime in 2025 orso
Quoted 1 line
Quoted 1 line
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 556
Quoted 1 line
scripts/qapi/parser.py +0
-0# after we've fully transitioned to the newqapidoc
Quoted 9 lines
Quoted 9 lines
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 572
Quoted 9 lines
scripts/qapi/parser.py +3
-0# 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 nolonger "
Quoted 1 line
Quoted 1 line
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 573
Quoted 1 line
scripts/qapi/parser.py +1
-0+ "supported. Please use the '..qmp-example::' "
Quoted 1 line
Quoted 1 line
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 574
Quoted 1 line
scripts/qapi/parser.py +1
-0+ "directive, or other suitable markupinstead."
Quoted 4 lines
Quoted 4 lines
scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc':
Quoted 4 lines
scripts/qapi/parser.py +3
-0+ ) + raise QAPIParseError(self, emsg) + doc.new_tagged_section(self.info,
match.group(1))Quoted 3 lines
Quoted 3 lines
Review
Quoted 3 lines
scripts/qapi/parser.py +0
-0text = line[match.end():] if text:(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.jsonQuoted 19 lines
Quoted 9 lines
Quoted 9 lines
index
107123f8a8d..c71d65cd51f100644tests/qapi-schema/doc-good.json +1
-1@@ -172,12 +172,17 @@ # # Duis aute irure dolor # -# Example: +# .. qmp-example::Quoted 9 lines
tests/qapi-schema/doc-good.json line 179
Quoted 6 lines
tests/qapi-schema/doc-good.json +3
-2+# :title: Ideal fast-food burger situation # -# -> in -# <- out +# -> "in" +# <- "out"Heh, trickery to make the text right of -> and <- JSON.
Quoted 4 lines
O:-)
It's maybe *slightly* bad form, but it does help illustrate how the new directive is transformed when using text output modes in the test suite,
so
Quoted 1 line
I kept it. The new directive will simply not allow malformed JSON, so
this
Quoted 1 line
seemed like the simplest way to cheese that.
I figure an alternative would be a more flexible "...".
Two hunks up, you dumb one down:
- # Example:
+ # .. qmp-example::
#
# -> { "execute": "query-blockstats" }
# <- {
- # ... lots of output ...
+ # ...
# }
Quoted 9 lines
If
qmp_lexer.pyunderstood this more verbose ellipsis, we could use something like# -> ... input ... # <- ... output ...Worth the bother? Certainly not just for tests. Maybe for nicer examples in real documentation? Up to you!
Good idea. I'll have to see if it's easy to get the lexer to realize both "..." and "...(etc)..." as tokens without accidentally eating legitimate JSON between. Probably a standalone patch/miniseries.
Quoted 169 lines
Quoted 12 lines
Quoted 11 lines
tests/qapi-schema/doc-good.json line 187
Quoted 10 lines
tests/qapi-schema/doc-good.json +5
-1# -# Examples: +# Examples:: +# +# - Not a QMP code block +# - Merely a preformatted code block literal +# It isn't even an rST list. # - *verbatim* # - {braces}Quoted 2 lines
(And here, we test the use of non-QMP code block literals, esp. after the qmp-example directive, proving that language settings have been restored
to
Quoted 1 line
defaults.)
Appreciated.
Quoted 17 lines
Quoted 7 lines
Quoted 7 lines
tests/qapi-schema/doc-good.json +1
-1#@@ -199,11 +204,11 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Example: +# .. qmp-example::Quoted 9 lines
tests/qapi-schema/doc-good.json line 211
Quoted 6 lines
tests/qapi-schema/doc-good.json +2
-2# -# -> in +# -> "this example" # -# <- out +# <- "has no title"Same trickery.
Quoted 1 line
Do you want that changed ... ?
It's just a test, good enough.
Quoted 4 lines
Quoted 4 lines
Review
Quoted 4 lines
tests/qapi-schema/doc-good.json +0
-0## { 'command': 'cmd-boxed', 'boxed': true, 'data': 'Object',(quoted diff) +0
-0b/tests/qapi-schema/doc-good.out
Quoted 23 lines
Quoted 23 lines
Quoted 23 lines
index
bd876b6542d..eee18cd436a100644tests/qapi-schema/doc-good.out +12
-4@@ -184,13 +184,21 @@ frobnicate - 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.Quoted 8 lines
Quoted 8 lines
tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a
Quoted 8 lines
tests/qapi-schema/doc-good.out +1
-1- *verbatim* - {braces} - section=None + Note:: Ceci n'est pas une note section=Since@@ -202,10 +210,12 @@ If you're bored enough to read this, go see avideo of boxed cats
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
tests/qapi-schema/doc-good.out +2
-2a feature feature=cmd-feat2 another feature - section=Example - -> in + section=None +.. qmp-example::Quoted 8 lines
Quoted 8 lines
Review
Quoted 8 lines
tests/qapi-schema/doc-good.out +3
-1- <- out + -> "this example" + + <- "has no title" doc symbol=EVT_BOXED body=(quoted diff) +0
-0
b/tests/qapi-schema/doc-good.txtQuoted 11 lines
Quoted 9 lines
tests/qapi-schema/doc-good.txt Notes: · line 220
Quoted 8 lines
index
30d457e5488..cb37db606a6100644tests/qapi-schema/doc-good.txt +1
-0@@ -217,17 +217,16 @@ Notes: Duis aute irure dolor +Example: Ideal fast-food burger situation:No comment on the american making fast food burger jokes? :-(
I chuckled, but no witticism came to me, so...
Quoted 37 lines
Quoted 37 lines
Quoted 37 lines
tests/qapi-schema/doc-good.txt +9
-13-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 @@ Features "cmd-feat2" another feature +Example:: -Example -~~~~~~~ + -> "this example" - -> in - - <- out + <- "has no title"Quoted 4 lines
Quoted 2 lines
tests/qapi-schema/doc-good.txt Features · line 270
Quoted 1 line
tests/qapi-schema/doc-good.txt +0
-0"EVT_BOXED" (Event)Does this adequately resolve your qualms about .txt rendering for
examples?
I think you mean my "Rendering to text now loses the "Example" heading" on "[PATCH 13/13] qapi: convert "Example" sections to rST". The diff above demonstrates it's no longer lost.
There's a tiny issue you may or may not want to address: an example isn't always separated by a blank line. To reproduce, add my TODO hack to announce-self, and examine qemu-qmp-ref.txt:
"announce-self" (Command)
-------------------------Trigger generation of broadcast RARP frames to update network switches. This can be useful when network bonds fail-over the active slave.
Arguments
~~~~~~~~~
Quoted 10 lines
--> The members of "AnnounceParameters"
--> Example::-> { "execute": "announce-self", "arguments": { "initial": 50, "max": 550, "rounds": 10, "step": 50, "interfaces": ["vn2", "vn3"], "id": "bob" } } <- { "return": {} }
Oh, uh. I'm not sure how to fix that right away, but I'll try. No promises.
You achieved a clean & consistent look for notes and examples in the browser. Love it!