Skip to contentSkip to conversation

qapi: convert "Note" and "Example" sections to rST

PATCH Superseded John Snow 3 participants 53 messages Jun 19, 2024 – Jul 1, 2024

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

John Snow

author
#0 lore raw

cover qapi: convert "Note" and "Example" sections to rST

This series focuses primarily on converting our existing QAPI/QMP documentation to remove special "Note" and "Example" sections in favor of rST markup for the same.

This is being done primarily to reduce the number of specially parsed QAPI sections we have in favor of allowing fully arbitrary rST markup for greater flexibility and freedom in styling the rendered HTML documentation.

(A tangible side benefit is that the new qapidoc generator has fewer sections to reason about when it splices inherited documentation together for the QMP reference manual; docs largely preserve the order of documentation "as written" instead of needing to splice multiple separate sections together. A goal of the new generator is to eventually remove all tagged sections except for "members" and "features".)

Known issues:

- The caption syntax for QMP examples is a little ugly in rendered HTML output; My CSS intern wasn't available before publication time to fix it ;) -- Will fix with an amendment patch at next opportunity.

Any feedback not implemented should be interpreted as evidence of a forgetful (rather than a spiteful) mind. Please remind me where appropriate.

--js

John Snow (13):
[DO-NOT-MERGE]: Add some ad-hoc linting helpers.
qapi: linter fixups
docs/qapidoc: delint a tiny portion of the module qapi/parser: preserve indentation in QAPIDoc sections qapi/parser: fix comment parsing immediately following a doc block docs/qapidoc: fix nested parsing under untagged sections
qapi: fix non-compliant JSON examples
qapi: ensure all errors sections are uniformly typset
qapi: convert "Note" sections to plain rST
qapi: update prose in note blocks
qapi: add markup to note blocks
qapi/parser: don't parse rST markup as section headers
qapi: convert "Example" sections to rST

 docs/devel/qapi-code-gen.rst                  |  25 +--
 docs/sphinx/qapidoc.py                        | 103 ++++++++----
 qapi/acpi.json                                |   6 +-
 qapi/block-core.json                          | 148 +++++++++-------
 qapi/block.json                               |  62 ++++---
 qapi/char.json                                |  48 ++++--
 qapi/control.json                             |  32 ++--
 qapi/dump.json                                |  14 +-
 qapi/introspect.json                          |   6 +-
 qapi/machine-target.json                      |  29 ++--
 qapi/machine.json                             | 125 ++++++++------
 qapi/migration.json                           | 159 ++++++++++++------
 qapi/misc-target.json                         |  33 ++--
 qapi/misc.json                                | 139 ++++++++-------
 qapi/net.json                                 |  42 +++--
 qapi/pci.json                                 |  11 +-
 qapi/qapi-schema.json                         |   6 +-
 qapi/qdev.json                                |  45 ++---
 qapi/qom.json                                 |  39 +++--
 qapi/replay.json                              |  12 +-
 qapi/rocker.json                              |  30 ++--
 qapi/run-state.json                           |  63 ++++---
 qapi/sockets.json                             |  10 +-
 qapi/stats.json                               |  22 +--
 qapi/tpm.json                                 |   9 +-
 qapi/trace.json                               |   6 +-
 qapi/transaction.json                         |  13 +-
 qapi/ui.json                                  |  93 +++++-----
 qapi/vfio.json                                |   3 +-
 qapi/virtio.json                              |  50 +++---
 qapi/yank.json                                |   6 +-
 qga/qapi-schema.json                          |  48 +++---
 scripts/qapi-lint.sh                          |  59 +++++++
 scripts/qapi/Makefile                         |   5 +
 scripts/qapi/introspect.py                    |   8 +-
 scripts/qapi/parser.py                        |  40 ++++-
 scripts/qapi/schema.py                        |   6 +-
 scripts/qapi/visit.py                         |   5 +-
 tests/qapi-schema/doc-empty-section.err       |   2 +-
 tests/qapi-schema/doc-empty-section.json      |   2 +-
 tests/qapi-schema/doc-good.json               |  21 ++-
 tests/qapi-schema/doc-good.out                |  62 ++++---
 tests/qapi-schema/doc-good.txt                |  31 ++--
 .../qapi-schema/doc-interleaved-section.json  |   2 +-
 44 files changed, 1036 insertions(+), 644 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile
Signature · 1 line
2.44.0
author
#1 lore raw

PATCH 1/13 : Add some ad-hoc linting helpers.

These aren't ready for upstream inclusion, because they do not properly manage version dependencies, execution environment and so on. These are just the tools I use in my Own Special Environment :tm: for testing and debugging.

They've been tested only on Fedora 38 for right now, which means:

Python 3.11.4-1.fc38
pylint 2.17.4-2.fc38
mypy 1.4.0-1.fc38
isort 5.12.0-1.fc38
flake8 5.0.3-2.fc38

"Soon" :tm: I'll move the qapi generator code under the python/ directory to take advantage of the more robust linting infrastructure there, but that's going to happen after this series. Sorry about that!

---
 scripts/qapi-lint.sh  | 59 +++++++++++++++++++++++++++++++++++++++++++
 scripts/qapi/Makefile |  5 ++++
 2 files changed, 64 insertions(+)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile
scripts/qapi-lint.sh new file +59 -0
new file mode 100755
index 00000000000..ba13306f09e
@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+set -e
+
+if [[ -f qapi/.flake8 ]]; then
+    echo "flake8 --config=qapi/.flake8 qapi/"
+    flake8 --config=qapi/.flake8 qapi/
+fi
+if [[ -f qapi/pylintrc ]]; then
+    echo "pylint --rcfile=qapi/pylintrc qapi/"
+    pylint --rcfile=qapi/pylintrc qapi/
+fi
+if [[ -f qapi/mypy.ini ]]; then
+    echo "mypy --config-file=qapi/mypy.ini qapi/"
+    mypy --config-file=qapi/mypy.ini qapi/
+fi
+
+if [[ -f qapi/.isort.cfg ]]; then
+    pushd qapi
+    echo "isort -c ."
+    isort -c .
+    popd
+fi
+
+if [[ -f ../docs/sphinx/qapi-domain.py ]]; then
+    pushd ../docs/sphinx
+
+    echo "mypy --strict qapi-domain.py"
+    mypy --strict qapi-domain.py
+    echo "flake8 qapi-domain.py --max-line-length=99"
+    flake8 qapi-domain.py --max-line-length=99
+    echo "isort qapi-domain.py"
+    isort qapi-domain.py
+    echo "black --check qapi-domain.py"
+    black --check qapi-domain.py
+
+    popd
+fi
+
+if [[ -f ../docs/sphinx/qapidoc.py ]]; then
+    pushd ../docs/sphinx
+
+    echo "pylint --rc-file ../../scripts/qapi/pylintrc qapidoc.py"
+    PYTHONPATH=${HOME}/src/qemu/scripts/ pylint --rc-file ../../scripts/qapi/pylintrc qapidoc.py
+    echo "flake8 qapidoc.py --max-line-length=80"
+    flake8 qapidoc.py --max-line-length=80
+    echo "isort qapidoc.py"
+    isort qapidoc.py
+    echo "black --line-length 80 --check qapidoc.py"
+    black --line-length 80 --check qapidoc.py
+
+    popd
+fi
+
+pushd ../build
+make -j13
+make check-qapi-schema
+make docs
+make sphinxdocs
+popd
scripts/qapi/Makefile new file +5 -0
new file mode 100644
index 00000000000..314e8a5505e
@@ -0,0 +1,5 @@
+check:
+	isort -c .
+	flake8 .
+	cd .. && pylint --rcfile=qapi/pylintrc qapi
+	cd .. && mypy -p qapi --config-file=qapi/mypy.ini
Signature · 1 line
2.44.0
author
#2 lore raw

PATCH 2/13 qapi: linter fixups

In reply to John Snow

Fix minor irritants to pylint/flake8 et al.

(Yes, these need to be guarded by the Python tests. That's a work in progress, a series that's quite likely to follow once I finish this Sphinx project. Please pardon the temporary irritation.)

---
 scripts/qapi/introspect.py | 8 ++++----
 scripts/qapi/schema.py     | 6 +++---
 scripts/qapi/visit.py      | 5 +++--
 3 files changed, 10 insertions(+), 9 deletions(-)
scripts/qapi/introspect.py +4 -4
index 86c075a6ad2..ac14b20f308 100644
@@ -27,8 +27,8 @@
 from .schema import (
     QAPISchema,
     QAPISchemaAlternatives,
-    QAPISchemaBranches,
     QAPISchemaArrayType,
+    QAPISchemaBranches,
     QAPISchemaBuiltinType,
     QAPISchemaEntity,
     QAPISchemaEnumMember,
@@ -233,9 +233,9 @@ def _use_type(self, typ: QAPISchemaType) -> str:
             typ = type_int
         elif (isinstance(typ, QAPISchemaArrayType) and
               typ.element_type.json_type() == 'int'):
-            type_intList = self._schema.lookup_type('intList')
-            assert type_intList
-            typ = type_intList
+            type_intlist = self._schema.lookup_type('intList')
+            assert type_intlist
+            typ = type_intlist
         # Add type to work queue if new
         if typ not in self._used_types:
             self._used_types.append(typ)
scripts/qapi/schema.py +3 -3
index 721c470d2b8..d65c35f6ee6 100644
@@ -730,6 +730,7 @@ def set_defined_in(self, name: str) -> None:
         for v in self.variants:
             v.set_defined_in(name)
 
+    # pylint: disable=unused-argument
     def check(
             self, schema: QAPISchema, seen: Dict[str, QAPISchemaMember]
     ) -> None:
@@ -1166,7 +1167,7 @@ def _def_definition(self, defn: QAPISchemaDefinition) -> None:
                 defn.info, "%s is already defined" % other_defn.describe())
         self._entity_dict[defn.name] = defn
 
-    def lookup_entity(self,name: str) -> Optional[QAPISchemaEntity]:
+    def lookup_entity(self, name: str) -> Optional[QAPISchemaEntity]:
         return self._entity_dict.get(name)
 
     def lookup_type(self, name: str) -> Optional[QAPISchemaType]:
@@ -1302,11 +1303,10 @@ def _make_implicit_object_type(
         name = 'q_obj_%s-%s' % (name, role)
         typ = self.lookup_entity(name)
         if typ:
-            assert(isinstance(typ, QAPISchemaObjectType))
+            assert isinstance(typ, QAPISchemaObjectType)
             # The implicit object type has multiple users.  This can
             # only be a duplicate definition, which will be flagged
             # later.
-            pass
         else:
             self._def_definition(QAPISchemaObjectType(
                 name, info, None, ifcond, None, None, members, None))
scripts/qapi/visit.py +3 -2
index e766acaac92..12f92e429f6 100644
@@ -280,8 +280,9 @@ def gen_visit_alternate(name: str,
         abort();
     default:
         assert(visit_is_input(v));
-        error_setg(errp, "Invalid parameter type for '%%s', expected: %(name)s",
-                         name ? name : "null");
+        error_setg(errp,
+                   "Invalid parameter type for '%%s', expected: %(name)s",
+                   name ? name : "null");
         /* Avoid passing invalid *obj to qapi_free_%(c_name)s() */
         g_free(*obj);
         *obj = NULL;
Signature · 1 line
2.44.0
author
#3 lore raw

PATCH 3/13 docs/qapidoc: delint a tiny portion of the module

In reply to John Snow

In a forthcoming series that adds a new QMP documentation generator, it will be helpful to have a linting baseline. However, there's no need to shuffle around the deck chairs too much, because most of this code will be removed once that new qapidoc generator (the "transmogrifier") is in place.

To ease my pain: just turn off the black auto-formatter for most, but not all, of qapidoc.py. This will help ensure that *new* code follows a coding standard without bothering too much with cleaning up the existing code.

Code that I intend to keep is still subject to the delinting beam.

---
 docs/sphinx/qapidoc.py | 66 +++++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 26 deletions(-)
docs/sphinx/qapidoc.py +40 -26
index f270b494f01..e675966defa 100644
@@ -28,33 +28,42 @@
 import re
 
 from docutils import nodes
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import ViewList
-from docutils.parsers.rst import directives, Directive
-from sphinx.errors import ExtensionError
-from sphinx.util.nodes import nested_parse_with_titles
-import sphinx
-from qapi.gen import QAPISchemaVisitor
 from qapi.error import QAPIError, QAPISemError
+from qapi.gen import QAPISchemaVisitor
 from qapi.schema import QAPISchema
 
+import sphinx
+from sphinx.errors import ExtensionError
+from sphinx.util.nodes import nested_parse_with_titles
+
 
 # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
 # use switch_source_input. Check borrowed from kerneldoc.py.
-Use_SSI = sphinx.__version__[:3] >= '1.7'
-if Use_SSI:
+USE_SSI = sphinx.__version__[:3] >= "1.7"
+if USE_SSI:
     from sphinx.util.docutils import switch_source_input
 else:
-    from sphinx.ext.autodoc import AutodocReporter
+    from sphinx.ext.autodoc import (  # pylint: disable=no-name-in-module
+        AutodocReporter,
+    )
 
 
-__version__ = '1.0'
+__version__ = "1.0"
 
 
+# Disable black auto-formatter until re-enabled:
+# fmt: off
+
 # Function borrowed from pydash, which is under the MIT license
 def intersperse(iterable, separator):
     """Yield the members of *iterable* interspersed with *separator*."""
     iterable = iter(iterable)
-    yield next(iterable)
+    try:
+        yield next(iterable)
+    except StopIteration:
+        return
     for item in iterable:
         yield separator
         yield item
@@ -451,6 +460,10 @@ def get_document_nodes(self):
         return self._top_node.children
 
 
+# Turn the black formatter on for the rest of the file.
+# fmt: on
+
+
 class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     """A QAPI schema visitor which adds Sphinx dependencies each module
 
@@ -458,34 +471,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     that the generated documentation output depends on the input
     schema file associated with each module in the QAPI input.
     """
+
     def __init__(self, env, qapidir):
         self._env = env
         self._qapidir = qapidir
 
     def visit_module(self, name):
         if name != "./builtin":
-            qapifile = self._qapidir + '/' + name
+            qapifile = self._qapidir + "/" + name
             self._env.note_dependency(os.path.abspath(qapifile))
         super().visit_module(name)
 
 
 class QAPIDocDirective(Directive):
     """Extract documentation from the specified QAPI .json file"""
+
     required_argument = 1
     optional_arguments = 1
-    option_spec = {
-        'qapifile': directives.unchanged_required
-    }
+    option_spec = {"qapifile": directives.unchanged_required}
     has_content = False
 
     def new_serialno(self):
         """Return a unique new ID string suitable for use as a node's ID"""
         env = self.state.document.settings.env
-        return 'qapidoc-%d' % env.new_serialno('qapidoc')
+        return "qapidoc-%d" % env.new_serialno("qapidoc")
 
     def run(self):
         env = self.state.document.settings.env
-        qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0]
+        qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
 
         try:
@@ -523,13 +536,14 @@ def do_parse(self, rstlist, node):
         # 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:
+        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)
+                rstlist, self.state.memo.reporter
+            )
             try:
                 nested_parse_with_titles(self.state, rstlist, node)
             finally:
@@ -537,12 +551,12 @@ def do_parse(self, rstlist, node):
 
 
 def setup(app):
-    """ Register qapi-doc directive with Sphinx"""
-    app.add_config_value('qapidoc_srctree', None, 'env')
-    app.add_directive('qapi-doc', QAPIDocDirective)
+    """Register qapi-doc directive with Sphinx"""
+    app.add_config_value("qapidoc_srctree", None, "env")
+    app.add_directive("qapi-doc", QAPIDocDirective)
 
-    return dict(
-        version=__version__,
-        parallel_read_safe=True,
-        parallel_write_safe=True
-    )
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }
Signature · 1 line
2.44.0
Reviewed-by on v1 3/13
#4 lore raw

Re: [PATCH 03/13] docs/qapidoc: delint a tiny portion of the module

Quoted 62 lines · John Snow

In a forthcoming series that adds a new QMP documentation generator, it will be helpful to have a linting baseline. However, there's no need to shuffle around the deck chairs too much, because most of this code will be removed once that new qapidoc generator (the "transmogrifier") is in place.

To ease my pain: just turn off the black auto-formatter for most, but not all, of qapidoc.py. This will help ensure that *new* code follows a coding standard without bothering too much with cleaning up the existing code.

Code that I intend to keep is still subject to the delinting beam.

---
 docs/sphinx/qapidoc.py | 66 +++++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 26 deletions(-)
docs/sphinx/qapidoc.py +14 -9
index f270b494f01..e675966defa 100644
@@ -28,33 +28,42 @@
 import re
 
 from docutils import nodes
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import ViewList
-from docutils.parsers.rst import directives, Directive
-from sphinx.errors import ExtensionError
-from sphinx.util.nodes import nested_parse_with_titles
-import sphinx
-from qapi.gen import QAPISchemaVisitor
 from qapi.error import QAPIError, QAPISemError
+from qapi.gen import QAPISchemaVisitor
 from qapi.schema import QAPISchema
 
+import sphinx
+from sphinx.errors import ExtensionError
+from sphinx.util.nodes import nested_parse_with_titles
+
 
 # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
 # use switch_source_input. Check borrowed from kerneldoc.py.
-Use_SSI = sphinx.__version__[:3] >= '1.7'
-if Use_SSI:
+USE_SSI = sphinx.__version__[:3] >= "1.7"
+if USE_SSI:
     from sphinx.util.docutils import switch_source_input
 else:
-    from sphinx.ext.autodoc import AutodocReporter
+    from sphinx.ext.autodoc import (  # pylint: disable=no-name-in-module
+        AutodocReporter,
+    )
 
 
-__version__ = '1.0'
+__version__ = "1.0"
 
 
+# Disable black auto-formatter until re-enabled:
+# fmt: off

docs/sphinx/qapidoc.py line 66

Quoted 10 lines
docs/sphinx/qapidoc.py +5 -1
+
 # Function borrowed from pydash, which is under the MIT license
 def intersperse(iterable, separator):
     """Yield the members of *iterable* interspersed with *separator*."""
     iterable = iter(iterable)
-    yield next(iterable)
+    try:
+        yield next(iterable)
+    except StopIteration:
+        return

This gets rid of pylint's

docs/sphinx/qapidoc.py:82:10: R1708: Do not raise StopIteration in generator, use return statement instead (stop-iteration-return)

I considered the same change some time ago, and decided against it to avoid deviating from pydash. StopIteration would be a programming error here.

Please *delete* the function instead: commit fd62bff901b removed its last use. I'd do it in a separate commit, but that's up to you.

Quoted 17 lines
docs/sphinx/qapidoc.py +4 -0
     for item in iterable:
         yield separator
         yield item
@@ -451,6 +460,10 @@ def get_document_nodes(self):
         return self._top_node.children
 
 
+# Turn the black formatter on for the rest of the file.
+# fmt: on
+
+
 class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     """A QAPI schema visitor which adds Sphinx dependencies each module
 
@@ -458,34 +471,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     that the generated documentation output depends on the input
     schema file associated with each module in the QAPI input.

docs/sphinx/qapidoc.py class QAPISchemaGenDepVisitor(QAPISchemaVisitor): · line 481

Quoted 10 lines
docs/sphinx/qapidoc.py +2 -1
     """
+
     def __init__(self, env, qapidir):
         self._env = env
         self._qapidir = qapidir
 
     def visit_module(self, name):
         if name != "./builtin":
-            qapifile = self._qapidir + '/' + name
+            qapifile = self._qapidir + "/" + name

The string literal quote changes are mildly annoying. But since by your good work you're effectively appointing yourself maintainer of this file... ;)

Quoted 56 lines
docs/sphinx/qapidoc.py +10 -10
             self._env.note_dependency(os.path.abspath(qapifile))
         super().visit_module(name)
 
 
 class QAPIDocDirective(Directive):
     """Extract documentation from the specified QAPI .json file"""
+
     required_argument = 1
     optional_arguments = 1
-    option_spec = {
-        'qapifile': directives.unchanged_required
-    }
+    option_spec = {"qapifile": directives.unchanged_required}
     has_content = False
 
     def new_serialno(self):
         """Return a unique new ID string suitable for use as a node's ID"""
         env = self.state.document.settings.env
-        return 'qapidoc-%d' % env.new_serialno('qapidoc')
+        return "qapidoc-%d" % env.new_serialno("qapidoc")
 
     def run(self):
         env = self.state.document.settings.env
-        qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0]
+        qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
 
         try:
@@ -523,13 +536,14 @@ def do_parse(self, rstlist, node):
         # 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:
+        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)
+                rstlist, self.state.memo.reporter
+            )
             try:
                 nested_parse_with_titles(self.state, rstlist, node)
             finally:
@@ -537,12 +551,12 @@ def do_parse(self, rstlist, node):
 
 
 def setup(app):
-    """ Register qapi-doc directive with Sphinx"""
-    app.add_config_value('qapidoc_srctree', None, 'env')
-    app.add_directive('qapi-doc', QAPIDocDirective)
+    """Register qapi-doc directive with Sphinx"""
+    app.add_config_value("qapidoc_srctree", None, "env")
+    app.add_directive("qapi-doc", QAPIDocDirective)
 

docs/sphinx/qapidoc.py def do_parse(self, rstlist, node): · line 562

Quoted 10 lines
docs/sphinx/qapidoc.py +5 -5
-    return dict(
-        version=__version__,
-        parallel_read_safe=True,
-        parallel_write_safe=True
-    )
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

With intersperse() deleted

author
#5 lore raw

Re: [PATCH 03/13] docs/qapidoc: delint a tiny portion of the module

Quoted 81 lines · Markus Armbruster
Quoted 42 lines · John Snow

In a forthcoming series that adds a new QMP documentation generator, it will be helpful to have a linting baseline. However, there's no need to shuffle around the deck chairs too much, because most of this code will be removed once that new qapidoc generator (the "transmogrifier") is in place.

To ease my pain: just turn off the black auto-formatter for most, but not all, of qapidoc.py. This will help ensure that *new* code follows a coding standard without bothering too much with cleaning up the existing code.

Code that I intend to keep is still subject to the delinting beam.

---
 docs/sphinx/qapidoc.py | 66 +++++++++++++++++++++++++-----------------
 1 file changed, 40 insertions(+), 26 deletions(-)
docs/sphinx/qapidoc.py +6 -5
index f270b494f01..e675966defa 100644
@@ -28,33 +28,42 @@
 import re
 
 from docutils import nodes
+from docutils.parsers.rst import Directive, directives
 from docutils.statemachine import ViewList
-from docutils.parsers.rst import directives, Directive
-from sphinx.errors import ExtensionError
-from sphinx.util.nodes import nested_parse_with_titles
-import sphinx
-from qapi.gen import QAPISchemaVisitor
 from qapi.error import QAPIError, QAPISemError
+from qapi.gen import QAPISchemaVisitor
 from qapi.schema import QAPISchema
 
+import sphinx
+from sphinx.errors import ExtensionError
+from sphinx.util.nodes import nested_parse_with_titles
+
 

docs/sphinx/qapidoc.py line 48

Quoted 10 lines
docs/sphinx/qapidoc.py +3 -3
 # Sphinx up to 1.6 uses AutodocReporter; 1.7 and later
 # use switch_source_input. Check borrowed from kerneldoc.py.
-Use_SSI = sphinx.__version__[:3] >= '1.7'
-if Use_SSI:
+USE_SSI = sphinx.__version__[:3] >= "1.7"
+if USE_SSI:
     from sphinx.util.docutils import switch_source_input
 else:
-    from sphinx.ext.autodoc import AutodocReporter
+    from sphinx.ext.autodoc import (  # pylint:

disable=no-name-in-module

Quoted 10 lines
docs/sphinx/qapidoc.py +5 -1
+        AutodocReporter,
+    )
 
 
-__version__ = '1.0'
+__version__ = "1.0"
 
 
+# Disable black auto-formatter until re-enabled:
+# fmt: off

docs/sphinx/qapidoc.py line 66

Quoted 10 lines
docs/sphinx/qapidoc.py +5 -1
+
 # Function borrowed from pydash, which is under the MIT license
 def intersperse(iterable, separator):
     """Yield the members of *iterable* interspersed with *separator*."""
     iterable = iter(iterable)
-    yield next(iterable)
+    try:
+        yield next(iterable)
+    except StopIteration:
+        return

This gets rid of pylint's

docs/sphinx/qapidoc.py:82:10: R1708: Do not raise StopIteration in
generator, use return statement instead (stop-iteration-return)

Quoted 7 lines

I considered the same change some time ago, and decided against it to avoid deviating from pydash. StopIteration would be a programming error here.

Please *delete* the function instead: commit fd62bff901b removed its last use. I'd do it in a separate commit, but that's up to you.

Oh! I didn't realize it wasn't being used. That's certainly easier :)

Quoted 23 lines
Quoted 23 lines
docs/sphinx/qapidoc.py +5 -0
     for item in iterable:
         yield separator
         yield item
@@ -451,6 +460,10 @@ def get_document_nodes(self):
         return self._top_node.children
 
 
+# Turn the black formatter on for the rest of the file.
+# fmt: on
+
+
 class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     """A QAPI schema visitor which adds Sphinx dependencies each module
 
@@ -458,34 +471,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor):
     that the generated documentation output depends on the input
     schema file associated with each module in the QAPI input.
     """
+
     def __init__(self, env, qapidir):
         self._env = env
         self._qapidir = qapidir
 
Quoted 9 lines

docs/sphinx/qapidoc.py class QAPISchemaGenDepVisitor(QAPISchemaVisitor): · line 481

Quoted 4 lines
docs/sphinx/qapidoc.py +1 -1
     def visit_module(self, name):
         if name != "./builtin":
-            qapifile = self._qapidir + '/' + name
+            qapifile = self._qapidir + "/" + name

The string literal quote changes are mildly annoying. But since by your good work you're effectively appointing yourself maintainer of this file... ;)

Mildly. However, I do think black is "close enough" on most style issues that I have absolutely no regret or hesitation using it for all new python development.

(I've been using it a lot in hobby code the last year and I find it to be remarkably helpful for my own consistency in style issues, it's indispensable for me.)

So in this series, I start using it because I essentially wind up rewriting this entire file and wanted an autoformatter so I could shut my brain off for stuff like this.

A "flag day" as you call it is likely coming soon to python/ where I'll start enforcing black standards. It just makes development easier to have a tool that just always DTRT. When I move QAPI there, it'll get the same treatment.

Quoted 69 lines
Quoted 7 lines
docs/sphinx/qapidoc.py +1 -0
             self._env.note_dependency(os.path.abspath(qapifile))
         super().visit_module(name)
 
 
 class QAPIDocDirective(Directive):
     """Extract documentation from the specified QAPI .json file"""
+

docs/sphinx/qapidoc.py class QAPISchemaGenDepVisitor(QAPISchemaVisitor):

Quoted 10 lines
docs/sphinx/qapidoc.py +1 -3
     required_argument = 1
     optional_arguments = 1
-    option_spec = {
-        'qapifile': directives.unchanged_required
-    }
+    option_spec = {"qapifile": directives.unchanged_required}
     has_content = False
 
     def new_serialno(self):
         """Return a unique new ID string suitable for use as a node's

ID"""

Quoted 39 lines
docs/sphinx/qapidoc.py +8 -7
         env = self.state.document.settings.env
-        return 'qapidoc-%d' % env.new_serialno('qapidoc')
+        return "qapidoc-%d" % env.new_serialno("qapidoc")
 
     def run(self):
         env = self.state.document.settings.env
-        qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0]
+        qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0]
         qapidir = os.path.dirname(qapifile)
 
         try:
@@ -523,13 +536,14 @@ def do_parse(self, rstlist, node):
         # 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:
+        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)
+                rstlist, self.state.memo.reporter
+            )
             try:
                 nested_parse_with_titles(self.state, rstlist, node)
             finally:
@@ -537,12 +551,12 @@ def do_parse(self, rstlist, node):
 
 
 def setup(app):
-    """ Register qapi-doc directive with Sphinx"""
-    app.add_config_value('qapidoc_srctree', None, 'env')
-    app.add_directive('qapi-doc', QAPIDocDirective)
+    """Register qapi-doc directive with Sphinx"""
+    app.add_config_value("qapidoc_srctree", None, "env")
+    app.add_directive("qapi-doc", QAPIDocDirective)
 

docs/sphinx/qapidoc.py def do_parse(self, rstlist, node): · line 562

Quoted 10 lines
docs/sphinx/qapidoc.py +5 -5
-    return dict(
-        version=__version__,
-        parallel_read_safe=True,
-        parallel_write_safe=True
-    )
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }

With intersperse() deleted

Quoted 2 lines

ありがとう

Quoted 1 line
author
#6 lore raw

PATCH 4/13 qapi/parser: preserve indentation in QAPIDoc sections

In reply to John Snow

Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

would have its body text be parsed as:
(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as:

```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

This understandably breaks the existing qapidoc.py; so a new function is added there to dedent the text for compatibility. Once the new generator is merged, this function will not be needed any longer and can be dropped.

I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST.

before:

69cde3d6f18b0f324badbb447d4381ce  manual_before/interop/qemu-ga-ref.html
446e9381833def2adc779f1b90f2215f  manual_before/interop/qemu-qmp-ref.html
df0ad6c26cb4c28b85d663fe44609c12  manual_before/interop/qemu-storage-daemon-qmp-ref.html

after:

69cde3d6f18b0f324badbb447d4381ce  manual/interop/qemu-ga-ref.html
446e9381833def2adc779f1b90f2215f  manual/interop/qemu-qmp-ref.html
df0ad6c26cb4c28b85d663fe44609c12  manual/interop/qemu-storage-daemon-qmp-ref.html
---
 docs/sphinx/qapidoc.py         | 29 ++++++++++++++++++++++++-----
 scripts/qapi/parser.py         |  5 +++--
 tests/qapi-schema/doc-good.out | 32 ++++++++++++++++----------------
 3 files changed, 43 insertions(+), 23 deletions(-)
docs/sphinx/qapidoc.py +24 -5
index e675966defa..f2f2005dd5f 100644
@@ -26,6 +26,7 @@
 
 import os
 import re
+import textwrap
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives
@@ -53,6 +54,21 @@
 __version__ = "1.0"
 
 
+def dedent(text: str) -> str:
+    # Temporary: In service of the new QAPI Sphinx domain, the QAPI doc
+    # parser now preserves indents in args/members/features text.
+    # QAPIDoc does not handle this well, so undo that change here.
+
+    lines = text.splitlines(True)
+    if re.match(r"\s+", lines[0]):
+        # First line is indented; description started on the line after
+        # the name. dedent the whole block.
+        return textwrap.dedent(text)
+
+    # Descr started on same line. Dedent line 2+.
+    return lines[0] + textwrap.dedent("".join(lines[1:]))
+
+
 # Disable black auto-formatter until re-enabled:
 # fmt: off
 
@@ -176,7 +192,7 @@ def _nodes_for_members(self, doc, what, base=None, branches=None):
             term = self._nodes_for_one_member(section.member)
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -214,7 +230,7 @@ def _nodes_for_enum_values(self, doc):
                 termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -249,7 +265,7 @@ def _nodes_for_features(self, doc):
         dlnode = nodes.definition_list()
         for section in doc.features.values():
             dlnode += self._make_dlitem(
-                [nodes.literal('', section.member.name)], section.text)
+                [nodes.literal('', section.member.name)], dedent(section.text))
             seen_item = True
 
         if not seen_item:
@@ -272,9 +288,12 @@ def _nodes_for_sections(self, doc):
                 continue
             snode = self._make_section(section.tag)
             if section.tag and section.tag.startswith('Example'):
-                snode += self._nodes_for_example(section.text)
+                snode += self._nodes_for_example(dedent(section.text))
             else:
-                self._parse_text_into_node(section.text, snode)
+                self._parse_text_into_node(
+                    dedent(section.text) if section.tag else section.text,
+                    snode,
+                )
             nodelist.append(snode)
         return nodelist
 
scripts/qapi/parser.py +3 -2
index 7b13a583ac1..43167ef0ab3 100644
@@ -437,6 +437,7 @@ def _match_at_name_colon(string: str) -> Optional[Match[str]]:
         return re.match(r'@([^:]*): *', string)
 
     def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
+        """get_doc_indented preserves indentation for later rST parsing."""
         self.accept(False)
         line = self.get_doc_line()
         while line == '':
@@ -448,7 +449,7 @@ def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
         indent = must_match(r'\s*', line).end()
         if not indent:
             return line
-        doc.append_line(line[indent:])
+        doc.append_line(line)
         prev_line_blank = False
         while True:
             self.accept(False)
@@ -465,7 +466,7 @@ def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
                     self,
                     "unexpected de-indent (expected at least %d spaces)" %
                     indent)
-            doc.append_line(line[indent:])
+            doc.append_line(line)
             prev_line_blank = True
 
     def get_doc_paragraph(self, doc: 'QAPIDoc') -> Optional[str]:
tests/qapi-schema/doc-good.out +16 -16
index 716a9a41026..435f6e6d768 100644
@@ -117,8 +117,8 @@ doc symbol=Base
     body=
 
     arg=base1
-description starts on a new line,
-minimally indented
+ description starts on a new line,
+ minimally indented
 doc symbol=Variant1
     body=
 A paragraph
@@ -145,8 +145,8 @@ doc symbol=Alternate
 
     arg=i
 description starts on the same line
-remainder indented the same
-@b is undocumented
+    remainder indented the same
+    @b is undocumented
     arg=b
 
     feature=alt-feat
@@ -158,11 +158,11 @@ doc symbol=cmd
     body=
 
     arg=arg1
-description starts on a new line,
-indented
+    description starts on a new line,
+    indented
     arg=arg2
 description starts on the same line
-remainder indented differently
+    remainder indented differently
     arg=arg3
 
     feature=cmd-feat1
@@ -178,16 +178,16 @@ some
     section=TODO
 frobnicate
     section=Notes
-- Lorem ipsum dolor sit amet
-- Ut enim ad minim veniam
+ - Lorem ipsum dolor sit amet
+ - Ut enim ad minim veniam
 
-Duis aute irure dolor
+ Duis aute irure dolor
     section=Example
--> in
-<- out
+ -> in
+ <- out
     section=Examples
-- *verbatim*
-- {braces}
+ - *verbatim*
+ - {braces}
     section=Since
 2.10
 doc symbol=cmd-boxed
@@ -198,9 +198,9 @@ a feature
     feature=cmd-feat2
 another feature
     section=Example
--> in
+ -> in
 
-<- out
+ <- out
 doc symbol=EVT_BOXED
     body=
 
Signature · 1 line
2.44.0
Reviewed-by on v1 4/13
#7 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 3 lines · John Snow

Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new

Suggest "remove indentation the same way get_doc_indented() did."

Quoted 5 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

Quoted 7 lines
```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

would have its body text be parsed as:

Suggest "parsed into".

Quoted 11 lines

(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here, too.

Quoted 16 lines
```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```
Quoted 7 lines

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

What do you mean by "reflowing"?

Quoted 9 lines

This understandably breaks the existing qapidoc.py; so a new function is added there to dedent the text for compatibility. Once the new generator is merged, this function will not be needed any longer and can be dropped.

I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST.

I think the remainder is unnecessary detail. Drop?

Quoted 32 lines

before:

69cde3d6f18b0f324badbb447d4381ce  manual_before/interop/qemu-ga-ref.html
446e9381833def2adc779f1b90f2215f  manual_before/interop/qemu-qmp-ref.html
df0ad6c26cb4c28b85d663fe44609c12  manual_before/interop/qemu-storage-daemon-qmp-ref.html

after:

69cde3d6f18b0f324badbb447d4381ce  manual/interop/qemu-ga-ref.html
446e9381833def2adc779f1b90f2215f  manual/interop/qemu-qmp-ref.html
df0ad6c26cb4c28b85d663fe44609c12  manual/interop/qemu-storage-daemon-qmp-ref.html
---
 docs/sphinx/qapidoc.py         | 29 ++++++++++++++++++++++++-----
 scripts/qapi/parser.py         |  5 +++--
 tests/qapi-schema/doc-good.out | 32 ++++++++++++++++----------------
 3 files changed, 43 insertions(+), 23 deletions(-)
docs/sphinx/qapidoc.py +1 -0
index e675966defa..f2f2005dd5f 100644
@@ -26,6 +26,7 @@
 
 import os
 import re
+import textwrap
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives

docs/sphinx/qapidoc.py line 60

Quoted 7 lines
docs/sphinx/qapidoc.py +4 -0
@@ -53,6 +54,21 @@
 __version__ = "1.0"
 
 
+def dedent(text: str) -> str:
+    # Temporary: In service of the new QAPI Sphinx domain, the QAPI doc
+    # parser now preserves indents in args/members/features text.
+    # QAPIDoc does not handle this well, so undo that change here.

A comment should explain how things are. This one explains how things have changed. Suggest:

# Adjust indentation to make description text parse as paragraph.

If we planned to keep this, we might want to explain in more detail, as I did in review of v1. But we don't.

Quoted 61 lines
docs/sphinx/qapidoc.py +19 -5
+
+    lines = text.splitlines(True)
+    if re.match(r"\s+", lines[0]):
+        # First line is indented; description started on the line after
+        # the name. dedent the whole block.
+        return textwrap.dedent(text)
+
+    # Descr started on same line. Dedent line 2+.
+    return lines[0] + textwrap.dedent("".join(lines[1:]))
+
+
 # Disable black auto-formatter until re-enabled:
 # fmt: off
 
@@ -176,7 +192,7 @@ def _nodes_for_members(self, doc, what, base=None, branches=None):
             term = self._nodes_for_one_member(section.member)
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -214,7 +230,7 @@ def _nodes_for_enum_values(self, doc):
                 termtext.extend(self._nodes_for_ifcond(section.member.ifcond))
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -249,7 +265,7 @@ def _nodes_for_features(self, doc):
         dlnode = nodes.definition_list()
         for section in doc.features.values():
             dlnode += self._make_dlitem(
-                [nodes.literal('', section.member.name)], section.text)
+                [nodes.literal('', section.member.name)], dedent(section.text))
             seen_item = True
 
         if not seen_item:
@@ -272,9 +288,12 @@ def _nodes_for_sections(self, doc):
                 continue
             snode = self._make_section(section.tag)
             if section.tag and section.tag.startswith('Example'):
-                snode += self._nodes_for_example(section.text)
+                snode += self._nodes_for_example(dedent(section.text))
             else:
-                self._parse_text_into_node(section.text, snode)
+                self._parse_text_into_node(
+                    dedent(section.text) if section.tag else section.text,
+                    snode,
+                )
             nodelist.append(snode)
         return nodelist
 
scripts/qapi/parser.py +0 -0
index 7b13a583ac1..43167ef0ab3 100644

scripts/qapi/parser.py def _match_at_name_colon(string: str) -> Optional[Match[str]]: · line 440

Quoted 4 lines
scripts/qapi/parser.py +1 -0
@@ -437,6 +437,7 @@ def _match_at_name_colon(string: str) -> Optional[Match[str]]:
         return re.match(r'@([^:]*): *', string)
 
     def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
+        """get_doc_indented preserves indentation for later rST parsing."""

A proper function comment explains what the function does. This one merely points out one minor aspect. Easy fix: delete it. Alternative
fix: write a proper function comment.

scripts/qapi/parser.py def _match_at_name_colon(string: str) -> Optional[Match[str]]: · line 443

Quoted 3 lines
scripts/qapi/parser.py +0 -0
         self.accept(False)
         line = self.get_doc_line()
         while line == '':

[...]

Just commit message and doc nitpicks, so

author
#8 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 8 lines · Markus Armbruster
Quoted 3 lines · John Snow

Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new

Suggest "remove indentation the same way get_doc_indented() did."

Aight.

Quoted 11 lines
Quoted 11 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```
Quoted 4 lines
Quoted 1 line

would have its body text be parsed as:

Suggest "parsed into".

Why? (I mean, I'll do it, but I don't see the semantic difference personally)

Quoted 38 lines
Quoted 11 lines

(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here, too.

Quoted 16 lines
```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```
Quoted 7 lines

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

Quoted 2 lines

What do you mean by "reflowing"?

Poorly phrased, was thinking about emacs too much. I mean munging the text post-hoc for the doc generator such that newlines are added or removed in the process of re-formatting text to get the proper indentation for the new rST form.

In prototyping, this got messy very quickly and was difficult to correlate source line numbers across the transformation.

It was easier to just not munge the text at all instead of munging it and then un-munging it.

(semantic satiation: munge munge munge munge.)

Quoted 5 lines
Quoted 5 lines

This understandably breaks the existing qapidoc.py; so a new function is added there to dedent the text for compatibility. Once the new generator is merged, this function will not be needed any longer and can be dropped.

Quoted 7 lines
Quoted 4 lines

I verified this patch changes absolutely nothing by comparing the md5sums of the QMP ref html pages both before and after the change, so it's certified inert. QAPI test output has been updated to reflect the new strategy of preserving indents for rST.

I think the remainder is unnecessary detail. Drop?

As long as you're convinced it's safe, it's done its job and we thank it for its service

🫡

Quoted 118 lines
Quoted 5 lines

before:

69cde3d6f18b0f324badbb447d4381ce manual_before/interop/qemu-ga-ref.html 446e9381833def2adc779f1b90f2215f manual_before/interop/qemu-qmp-ref.html df0ad6c26cb4c28b85d663fe44609c12

manual_before/interop/qemu-storage-daemon-qmp-ref.html

Quoted 6 lines

after:

69cde3d6f18b0f324badbb447d4381ce manual/interop/qemu-ga-ref.html 446e9381833def2adc779f1b90f2215f manual/interop/qemu-qmp-ref.html df0ad6c26cb4c28b85d663fe44609c12

manual/interop/qemu-storage-daemon-qmp-ref.html

Quoted 21 lines
---
 docs/sphinx/qapidoc.py         | 29 ++++++++++++++++++++++++-----
 scripts/qapi/parser.py         |  5 +++--
 tests/qapi-schema/doc-good.out | 32 ++++++++++++++++----------------
 3 files changed, 43 insertions(+), 23 deletions(-)
docs/sphinx/qapidoc.py +1 -0
index e675966defa..f2f2005dd5f 100644
@@ -26,6 +26,7 @@
 
 import os
 import re
+import textwrap
 
 from docutils import nodes
 from docutils.parsers.rst import Directive, directives

docs/sphinx/qapidoc.py line 60

Quoted 7 lines
docs/sphinx/qapidoc.py +4 -0
@@ -53,6 +54,21 @@
 __version__ = "1.0"
 
 
+def dedent(text: str) -> str:
+    # Temporary: In service of the new QAPI Sphinx domain, the QAPI doc
+    # parser now preserves indents in args/members/features text.
+    # QAPIDoc does not handle this well, so undo that change here.

A comment should explain how things are. This one explains how things have changed. Suggest:

# Adjust indentation to make description text parse as paragraph.

If we planned to keep this, we might want to explain in more detail, as I did in review of v1. But we don't.

docs/sphinx/qapidoc.py def _nodes_for_members(self, doc, what, base=None,

Quoted 15 lines
docs/sphinx/qapidoc.py +11 -0
+
+    lines = text.splitlines(True)
+    if re.match(r"\s+", lines[0]):
+        # First line is indented; description started on the line after
+        # the name. dedent the whole block.
+        return textwrap.dedent(text)
+
+    # Descr started on same line. Dedent line 2+.
+    return lines[0] + textwrap.dedent("".join(lines[1:]))
+
+
 # Disable black auto-formatter until re-enabled:
 # fmt: off
 
@@ -176,7 +192,7 @@ def _nodes_for_members(self, doc, what, base=None,

branches=None):

docs/sphinx/qapidoc.py def _nodes_for_enum_values(self, doc): · line 230

Quoted 10 lines
docs/sphinx/qapidoc.py +1 -1
             term = self._nodes_for_one_member(section.member)
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -214,7 +230,7 @@ def _nodes_for_enum_values(self, doc):
 

termtext.extend(self._nodes_for_ifcond(section.member.ifcond))

docs/sphinx/qapidoc.py def _nodes_for_features(self, doc): · line 268

Quoted 13 lines
docs/sphinx/qapidoc.py +2 -2
             # TODO drop fallbacks when undocumented members are outlawed
             if section.text:
-                defn = section.text
+                defn = dedent(section.text)
             else:
                 defn = [nodes.Text('Not documented')]
 
@@ -249,7 +265,7 @@ def _nodes_for_features(self, doc):
         dlnode = nodes.definition_list()
         for section in doc.features.values():
             dlnode += self._make_dlitem(
-                [nodes.literal('', section.member.name)], section.text)
+                [nodes.literal('', section.member.name)],

dedent(section.text))

docs/sphinx/qapidoc.py def _nodes_for_sections(self, doc): · line 294

Quoted 13 lines
docs/sphinx/qapidoc.py +3 -2
             seen_item = True
 
         if not seen_item:
@@ -272,9 +288,12 @@ def _nodes_for_sections(self, doc):
                 continue
             snode = self._make_section(section.tag)
             if section.tag and section.tag.startswith('Example'):
-                snode += self._nodes_for_example(section.text)
+                snode += self._nodes_for_example(dedent(section.text))
             else:
-                self._parse_text_into_node(section.text, snode)
+                self._parse_text_into_node(
+                    dedent(section.text) if section.tag else

section.text,

scripts/qapi/parser.py def _match_at_name_colon(string: str) ->

Quoted 10 lines
docs/sphinx/qapidoc.py +2 -0
+                    snode,
+                )
             nodelist.append(snode)
         return nodelist
 
scripts/qapi/parser.py +0 -0
index 7b13a583ac1..43167ef0ab3 100644
@@ -437,6 +437,7 @@ def _match_at_name_colon(string: str) ->

Optional[Match[str]]:

Quoted 2 lines
scripts/qapi/parser.py +0 -0
         return re.match(r'@([^:]*): *', string)
 
Quoted 8 lines

scripts/qapi/parser.py def _match_at_name_colon(string: str) -> · line 440

Quoted 2 lines
scripts/qapi/parser.py +1 -0
     def get_doc_indented(self, doc: 'QAPIDoc') -> Optional[str]:
+        """get_doc_indented preserves indentation for later rST

parsing."""

A proper function comment explains what the function does. This one merely points out one minor aspect. Easy fix: delete it. Alternative
fix: write a proper function comment.

Fair. I'll take a stab at writing a better one, but encourage inevitable tweaks to the phrasing to be handled by the maintainer afterwards ;)

Quoted 9 lines

scripts/qapi/parser.py def _match_at_name_colon(string: str) -> Optional[Match[str]]: · line 443

Quoted 3 lines
scripts/qapi/parser.py +0 -0
         self.accept(False)
         line = self.get_doc_line()
         while line == '':

[...]

Just commit message and doc nitpicks, so

Thanks! I'll make some good faith adjustments and keep the RB, but re-review before you merge and (please) feel free to make phrasing tweaks as you see fit.

Quoted 1 line
#9 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 25 lines · John Snow
Quoted 8 lines · Markus Armbruster
Quoted 3 lines · John Snow

Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new

Suggest "remove indentation the same way get_doc_indented() did."

Aight.

Quoted 11 lines
Quoted 11 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```
Quoted 8 lines
Quoted 4 lines
Quoted 1 line

would have its body text be parsed as:

Suggest "parsed into".

Why? (I mean, I'll do it, but I don't see the semantic difference personally)

"Parse as <language>" vs. "Parse into <representation>".

Quoted 46 lines
Quoted 38 lines
Quoted 11 lines

(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here, too.

Quoted 16 lines
```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```
Quoted 7 lines

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

Quoted 2 lines

What do you mean by "reflowing"?

Poorly phrased, was thinking about emacs too much. I mean munging the text post-hoc for the doc generator such that newlines are added or removed in the process of re-formatting text to get the proper indentation for the new rST form.

Quoted 7 lines

In prototyping, this got messy very quickly and was difficult to correlate source line numbers across the transformation.

It was easier to just not munge the text at all instead of munging it and then un-munging it.

(semantic satiation: munge munge munge munge.)

Is this about a possible alternative solution you explored? Keeping .get_doc_indented() as is, and then try to undo its damage?

[...]

author
#10 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 95 lines · Markus Armbruster
Quoted 1 line · John Snow

On Wed, Jun 19, 2024, 8:03 AM Markus Armbruster <[email protected]>

Quoted 4 lines · wrote:
Quoted 4 lines
Quoted 1 line · John Snow

Change get_doc_indented() to preserve indentation on all subsequent

text

Quoted 20 lines
Quoted 5 lines
Quoted 2 lines

lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new

Suggest "remove indentation the same way get_doc_indented() did."

Aight.

Quoted 11 lines
Quoted 11 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```
Quoted 8 lines
Quoted 4 lines
Quoted 1 line

would have its body text be parsed as:

Suggest "parsed into".

Why? (I mean, I'll do it, but I don't see the semantic difference personally)

"Parse as <language>" vs. "Parse into <representation>".

Quoted 9 lines
Quoted 9 lines
Quoted 9 lines

(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so

that

Quoted 6 lines
Quoted 6 lines
Quoted 2 lines

the entire block can be parsed directly as rST. This patch would now parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here, too.

Quoted 1 line
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists

in

Quoted 10 lines
Quoted 10 lines
Quoted 10 lines

rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the

continuation

Quoted 10 lines
Quoted 8 lines
Quoted 5 lines

of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

What do you mean by "reflowing"?

Poorly phrased, was thinking about emacs too much. I mean munging the

text

Quoted 2 lines

post-hoc for the doc generator such that newlines are added or removed in the process of re-formatting text to get the proper indentation for the

new

Quoted 3 lines

rST form.

In prototyping, this got messy very quickly and was difficult to

correlate

Quoted 2 lines

source line numbers across the transformation.

Quoted 8 lines
Quoted 4 lines

It was easier to just not munge the text at all instead of munging it and then un-munging it.

(semantic satiation: munge munge munge munge.)

Is this about a possible alternative solution you explored? Keeping .get_doc_indented() as is, and then try to undo its damage?

precisamente. That solution was categorically worse.

Quoted 3 lines

[...]

#11 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 92 lines · John Snow
Quoted 90 lines · Markus Armbruster
Quoted 25 lines · John Snow
Quoted 8 lines · Markus Armbruster
Quoted 3 lines · John Snow

Change get_doc_indented() to preserve indentation on all subsequent text lines, and create a compatibility dedent() function for qapidoc.py to remove that indentation. This is being done for the benefit of a new

Suggest "remove indentation the same way get_doc_indented() did."

Aight.

Quoted 11 lines
Quoted 11 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```
Quoted 8 lines
Quoted 4 lines
Quoted 1 line

would have its body text be parsed as:

Suggest "parsed into".

Why? (I mean, I'll do it, but I don't see the semantic difference personally)

"Parse as <language>" vs. "Parse into <representation>".

Quoted 52 lines
Quoted 38 lines
Quoted 11 lines

(first and final newline only for presentation)

```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line so that the entire block can be parsed directly as rST. This patch would now parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here, too.

Quoted 16 lines
```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field lists in rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```
Quoted 7 lines

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the continuation of a block-level element, and further allow the use of additional rST block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps preserve source line context for better rST error reporting from sphinx through generated source, too.

Quoted 2 lines

What do you mean by "reflowing"?

Poorly phrased, was thinking about emacs too much. I mean munging the text post-hoc for the doc generator such that newlines are added or removed in the process of re-formatting text to get the proper indentation for the new rST form.

In prototyping, this got messy very quickly and was difficult to correlate source line numbers across the transformation.

It was easier to just not munge the text at all instead of munging it and then un-munging it.

Quoted 7 lines
Quoted 5 lines
Quoted 1 line

(semantic satiation: munge munge munge munge.)

Is this about a possible alternative solution you explored? Keeping .get_doc_indented() as is, and then try to undo its damage?

precisamente. That solution was categorically worse.

Since .get_doc_indented() removes N spaces of indentation, we'd want to add back N spaces of indentation. But we can't know N, so I guess we'd make do with an arbitrary number. Where would reflowing come it?

I'd like you to express more clearly that you're talking about an alternative you rejected. Perhaps like this:

block-level constructs such as code blocks, lists, and other such markup.

The alternative would be to somehow undo .get_doc_indented()'s indentation changes in the new generator. Much messier.

Feel free to add more detail to the last paragraph.

Quoted 1 line
Quoted 1 line

[...]

author
#12 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 127 lines · Markus Armbruster
Quoted 1 line · John Snow

On Thu, Jun 20, 2024, 11:07 AM Markus Armbruster <[email protected]>

Quoted 4 lines · wrote:
Quoted 4 lines
Quoted 1 line · John Snow

On Wed, Jun 19, 2024, 8:03 AM Markus Armbruster <[email protected]>

Quoted 4 lines · wrote:
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 1 line · John Snow

Change get_doc_indented() to preserve indentation on all

subsequent text

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

lines, and create a compatibility dedent() function for qapidoc.py

to

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

remove that indentation. This is being done for the benefit of a

new

Quoted 31 lines
Quoted 31 lines
Quoted 18 lines
Quoted 3 lines

Suggest "remove indentation the same way get_doc_indented() did."

Aight.

Quoted 11 lines
Quoted 11 lines

qapidoc generator which requires that indentation in argument and features sections are preserved.

Prior to this patch, a section like this:

```
@name: lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```
Quoted 8 lines
Quoted 4 lines
Quoted 1 line

would have its body text be parsed as:

Suggest "parsed into".

Why? (I mean, I'll do it, but I don't see the semantic difference personally)

"Parse as <language>" vs. "Parse into <representation>".

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

(first and final newline only for presentation)

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
```
lorem ipsum
dolor sit amet
  consectetur adipiscing elit
```

We want to preserve the indentation for even the first body line

so that

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

the entire block can be parsed directly as rST. This patch would

now

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line

parse that segment as:

If you change "parsed as" to "parsed into" above, then do it here,

too.

Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
Quoted 9 lines
Quoted 9 lines

```
lorem ipsum
   dolor sit amet
     consectetur adipiscing elit
```

This is helpful for formatting arguments and features as field

lists in

Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Quoted 10 lines
Quoted 10 lines

rST, where the new generator will format this information as:

```
:arg type name: lorem ipsum
   dolor sit amet
     consectetur apidiscing elit
```

...and can be formed by the simple concatenation of the field list construct and the body text. The indents help preserve the

continuation

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

of a block-level element, and further allow the use of additional

rST

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

block-level constructs such as code blocks, lists, and other such markup. Avoiding reflowing the text conditionally also helps

preserve

Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line
Quoted 1 line

source line context for better rST error reporting from sphinx

through

Quoted 6 lines
Quoted 6 lines
Quoted 6 lines
Quoted 4 lines
Quoted 1 line

generated source, too.

What do you mean by "reflowing"?

Poorly phrased, was thinking about emacs too much. I mean munging the

text

Quoted 1 line
Quoted 1 line
Quoted 1 line

post-hoc for the doc generator such that newlines are added or

removed in

Quoted 1 line
Quoted 1 line
Quoted 1 line

the process of re-formatting text to get the proper indentation for

the new

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

rST form.

In prototyping, this got messy very quickly and was difficult to

correlate

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

source line numbers across the transformation.

It was easier to just not munge the text at all instead of munging it

and

Quoted 9 lines
Quoted 7 lines
Quoted 3 lines

then un-munging it.

(semantic satiation: munge munge munge munge.)

Is this about a possible alternative solution you explored? Keeping .get_doc_indented() as is, and then try to undo its damage?

precisamente. That solution was categorically worse.

Since .get_doc_indented() removes N spaces of indentation, we'd want to add back N spaces of indentation. But we can't know N, so I guess we'd make do with an arbitrary number. Where would reflowing come it?

I'd like you to express more clearly that you're talking about an alternative you rejected. Perhaps like this:

Quoted 8 lines

block-level constructs such as code blocks, lists, and other such markup.

The alternative would be to somehow undo .get_doc_indented()'s indentation changes in the new generator. Much messier.

Feel free to add more detail to the last paragraph.

Eh, I just deleted it. I recall running into troubles but I can't articulate the precise conditions because as you point out, it's a doomed strategy for other reasons - you can't reconstruct the proper indentation.

This patch is still the correct way to go, so I don't have to explain my failures at length in the commit message ... I just like giving people clues for *why* I decided to implement things a certain way, because I often find that more instructive than the "how". In this case, the "why" is probably more properly summarized as "it's a total shitshow in that direction, trust me"

--js

#13 lore raw

Re: [PATCH 04/13] qapi/parser: preserve indentation in QAPIDoc sections

Quoted 1 line · John Snow

On Fri, Jun 21, 2024 at 2:38 AM Markus Armbruster <[email protected]> wrote:

[...]

Quoted 12 lines
Quoted 11 lines

I'd like you to express more clearly that you're talking about an alternative you rejected. Perhaps like this:

block-level constructs such as code blocks, lists, and other such markup.

The alternative would be to somehow undo .get_doc_indented()'s indentation changes in the new generator. Much messier.

Feel free to add more detail to the last paragraph.

Quoted 8 lines

Eh, I just deleted it. I recall running into troubles but I can't articulate the precise conditions because as you point out, it's a doomed strategy for other reasons - you can't reconstruct the proper indentation.

This patch is still the correct way to go, so I don't have to explain my failures at length in the commit message ... I just like giving people clues for *why* I decided to implement things a certain way, because I often find that more instructive than the "how".

"Why" tends to be much more useful in a commit message than "how". I should be able to figure out "how" by reading the patch, whereas for "why", I may have to read the author's mind.

Quoted 3 lines

In this case, the "why" is
probably more properly summarized as "it's a total shitshow in that direction, trust me"

The right amount of detail is often not obvious. Use your judgement.

author
#14 lore raw

PATCH 5/13 qapi/parser: fix comment parsing immediately following a doc block

In reply to John Snow

If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that.

e.g.

Quoted 5 lines

##
# = Hello World!
##

# I'm a comment!

will break the parser, because it does not properly ignore the comment token if it immediately follows a doc block.

Fixes 3d035cd2cca6 (qapi: Rewrite doc comment parser)
---
 scripts/qapi/parser.py          | 2 +-
 tests/qapi-schema/doc-good.json | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)
scripts/qapi/parser.py +1 -1
index 43167ef0ab3..dfd6a6c5bee 100644
@@ -584,7 +584,7 @@ def get_doc(self) -> 'QAPIDoc':
                 line = self.get_doc_line()
                 first = False
 
-        self.accept(False)
+        self.accept()
         doc.end()
         return doc
 
tests/qapi-schema/doc-good.json +2 -0
index de38a386e8f..8b39eb946af 100644
@@ -55,6 +55,8 @@
 # - {braces}
 ##
 
+# Not a doc comment
+
 ##
 # @Enum:
 #
Signature · 1 line
2.44.0
Reviewed-by on v1 5/13
#15 lore raw

Re: [PATCH 05/13] qapi/parser: fix comment parsing immediately following a doc block

Quoted 39 lines · John Snow

If a comment immediately follows a doc block, the parser doesn't ignore that token appropriately. Fix that.

e.g.

Quoted 5 lines

##
# = Hello World!
##

# I'm a comment!

will break the parser, because it does not properly ignore the comment token if it immediately follows a doc block.

Fixes 3d035cd2cca6 (qapi: Rewrite doc comment parser)
---
 scripts/qapi/parser.py          | 2 +-
 tests/qapi-schema/doc-good.json | 2 ++
 2 files changed, 3 insertions(+), 1 deletion(-)
scripts/qapi/parser.py +1 -1
index 43167ef0ab3..dfd6a6c5bee 100644
@@ -584,7 +584,7 @@ def get_doc(self) -> 'QAPIDoc':
                 line = self.get_doc_line()
                 first = False
 
-        self.accept(False)
+        self.accept()
         doc.end()
         return doc
 
tests/qapi-schema/doc-good.json +0 -0
index de38a386e8f..8b39eb946af 100644

tests/qapi-schema/doc-good.json line 62

Quoted 8 lines
tests/qapi-schema/doc-good.json +2 -0
@@ -55,6 +55,8 @@
 # - {braces}
 ##
 
+# Not a doc comment
+
 ##
 # @Enum:
 #
author
#16 lore raw

PATCH 6/13 docs/qapidoc: fix nested parsing under untagged sections

In reply to John Snow

Sphinx does not like sections without titles, because it wants to convert every section into a reference. When there is no title, it struggles to do this and transforms the tree inproperly.

Depending on the rST used, this may result in an assertion error deep in the docutils HTMLWriter.

(Observed when using ".. admonition:: Notes" under such a section - When this is transformed with its own <title> element, Sphinx is fooled into believing this title belongs to the section and incorrect mutates the docutils tree, leading to errors during rendering time.)

When parsing an untagged section (free paragraphs), skip making a hollow section and instead append the parse results to the prior section.

Many Bothans died to bring us this information.

---
 docs/sphinx/qapidoc.py | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
docs/sphinx/qapidoc.py +11 -5
index f2f2005dd5f..66cf254a624 100644
@@ -286,14 +286,20 @@ def _nodes_for_sections(self, doc):
             if section.tag and section.tag == 'TODO':
                 # Hide TODO: sections
                 continue
+
+            if not section.tag:
+                # Sphinx cannot handle sectionless titles;
+                # Instead, just append the results to the prior section.
+                container = nodes.container()
+                self._parse_text_into_node(section.text, container)
+                nodelist += container.children
+                continue
+
             snode = self._make_section(section.tag)
-            if section.tag and section.tag.startswith('Example'):
+            if section.tag.startswith('Example'):
                 snode += self._nodes_for_example(dedent(section.text))
             else:
-                self._parse_text_into_node(
-                    dedent(section.text) if section.tag else section.text,
-                    snode,
-                )
+                self._parse_text_into_node(dedent(section.text), snode)
             nodelist.append(snode)
         return nodelist
 
Signature · 1 line
2.44.0
Acked-by on v1 6/13
#17 lore raw

Re: [PATCH 06/13] docs/qapidoc: fix nested parsing under untagged sections

Quoted 41 lines · John Snow

Sphinx does not like sections without titles, because it wants to convert every section into a reference. When there is no title, it struggles to do this and transforms the tree inproperly.

Depending on the rST used, this may result in an assertion error deep in the docutils HTMLWriter.

(Observed when using ".. admonition:: Notes" under such a section - When this is transformed with its own <title> element, Sphinx is fooled into believing this title belongs to the section and incorrect mutates the docutils tree, leading to errors during rendering time.)

When parsing an untagged section (free paragraphs), skip making a hollow section and instead append the parse results to the prior section.

Many Bothans died to bring us this information.

---
 docs/sphinx/qapidoc.py | 16 +++++++++++-----
 1 file changed, 11 insertions(+), 5 deletions(-)
docs/sphinx/qapidoc.py +9 -1
index f2f2005dd5f..66cf254a624 100644
@@ -286,14 +286,20 @@ def _nodes_for_sections(self, doc):
             if section.tag and section.tag == 'TODO':
                 # Hide TODO: sections
                 continue
+
+            if not section.tag:
+                # Sphinx cannot handle sectionless titles;
+                # Instead, just append the results to the prior section.
+                container = nodes.container()
+                self._parse_text_into_node(section.text, container)
+                nodelist += container.children
+                continue
+
             snode = self._make_section(section.tag)
-            if section.tag and section.tag.startswith('Example'):

docs/sphinx/qapidoc.py def _nodes_for_sections(self, doc): · line 304

Quoted 10 lines
docs/sphinx/qapidoc.py +2 -4
+            if section.tag.startswith('Example'):
                 snode += self._nodes_for_example(dedent(section.text))
             else:
-                self._parse_text_into_node(
-                    dedent(section.text) if section.tag else section.text,
-                    snode,
-                )
+                self._parse_text_into_node(dedent(section.text), snode)
             nodelist.append(snode)
         return nodelist
author
#18 lore raw

PATCH 7/13 qapi: fix non-compliant JSON examples

In reply to John Snow

The new QMP documentation generator wants to parse all examples as "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html)
that allows the use of "->", "<-" and "..." tokens to denote QMP protocol flow with elisions, but otherwise defers to the JSON lexer.

To utilize this lexer for the existing QAPI documentation, we need them to conform to a standard so that they lex and render correctly. Once the QMP lexer is active for examples, errant QMP/JSON will produce warning messages and fail the build.

Fix any invalid JSON found in QAPI documentation (identified by attempting to lex all examples as QMP; see subsequent commits). Further, the QMP lexer still supports elisions, but they must be represented as the value "...", so three examples have been adjusted to support that format here.

---
 qapi/control.json   | 3 ++-
 qapi/machine.json   | 2 +-
 qapi/migration.json | 2 +-
 qapi/misc.json      | 3 ++-
 qapi/net.json       | 6 +++---
 qapi/rocker.json    | 2 +-
 qapi/ui.json        | 2 +-
 7 files changed, 11 insertions(+), 9 deletions(-)
qapi/control.json +2 -1
index 6bdbf077c2e..10c906fa0e7 100644
@@ -145,7 +145,8 @@
 #             },
 #             {
 #                "name":"system_powerdown"
-#             }
+#             },
+#             ...
 #          ]
 #        }
 #
qapi/machine.json +1 -1
index 453feb93473..172b38e343e 100644
@@ -1057,7 +1057,7 @@
 #            "vcpus-count": 1 },
 #          { "props": { "core-id": 0 }, "type": "POWER8-spapr-cpu-core",
 #            "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
-#        ]}'
+#        ]}
 #
 #     For pc machine type started with -smp 1,maxcpus=2:
 #
qapi/migration.json +1 -1
index 470f746cc5f..7d4b567eb59 100644
@@ -2087,7 +2087,7 @@
 # Example:
 #
 #     -> {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1,
-#                                                     'sample-pages': 512} }
+#                                                     "sample-pages": 512} }
 #     <- { "return": {} }
 #
 #     Measure dirty rate using dirty bitmap for 500 milliseconds:
qapi/misc.json +2 -1
index ec30e5c570a..4b41e15dcd4 100644
@@ -287,7 +287,8 @@
 #
 # Example:
 #
-#     -> { "execute": "get-win32-socket", "arguments": { "info": "abcd123..", fdname": "skclient" } }
+#     -> { "execute": "get-win32-socket",
+#          "arguments": { "info": "abcd123..", "fdname": "skclient" } }
 #     <- { "return": {} }
 ##
 { 'command': 'get-win32-socket', 'data': {'info': 'str', 'fdname': 'str'}, 'if': 'CONFIG_WIN32' }
qapi/net.json +3 -3
index 0f5a259475e..c19df435a53 100644
@@ -1003,9 +1003,9 @@
 #
 # Example:
 #
-#     <- { 'event': 'NETDEV_STREAM_DISCONNECTED',
-#          'data': {'netdev-id': 'netdev0'},
-#          'timestamp': {'seconds': 1663330937, 'microseconds': 526695} }
+#     <- { "event": "NETDEV_STREAM_DISCONNECTED",
+#          "data": {"netdev-id": "netdev0"},
+#          "timestamp": {"seconds": 1663330937, "microseconds": 526695} }
 ##
 { 'event': 'NETDEV_STREAM_DISCONNECTED',
   'data': { 'netdev-id': 'str' } }
qapi/rocker.json +1 -1
index 5635cf174fd..f5225eb62cc 100644
@@ -250,7 +250,7 @@
 #                       "action": {"goto-tbl": 10},
 #                       "mask": {"in-pport": 4294901760}
 #                      },
-#                      {...more...},
+#                      {...},
 #        ]}
 ##
 { 'command': 'query-rocker-of-dpa-flows',
qapi/ui.json +1 -1
index f610bce118a..c12f5292571 100644
@@ -361,7 +361,7 @@
 #                    "channel-id": 0,
 #                    "tls": false
 #                 },
-#                 [ ... more channels follow ... ]
+#                 ...
 #              ]
 #           }
 #        }
Signature · 1 line
2.44.0
Reviewed-by on v1 7/13
#19 lore raw

Re: [PATCH 07/13] qapi: fix non-compliant JSON examples

Quoted 11 lines · John Snow

The new QMP documentation generator wants to parse all examples as "QMP". We have an existing QMP lexer in docs/sphinx/qmp_lexer.py (Seen in-use here: https://qemu-project.gitlab.io/qemu/interop/bitmaps.html)
that allows the use of "->", "<-" and "..." tokens to denote QMP protocol flow with elisions, but otherwise defers to the JSON lexer.

To utilize this lexer for the existing QAPI documentation, we need them to conform to a standard so that they lex and render correctly. Once the QMP lexer is active for examples, errant QMP/JSON will produce warning messages and fail the build.

Quoted 7 lines

Fix any invalid JSON found in QAPI documentation (identified by attempting to lex all examples as QMP; see subsequent commits). Further, the QMP lexer still supports elisions, but they must be represented as the value "...", so three examples have been adjusted to support that format here.

author
#20 lore raw

PATCH 8/13 qapi: ensure all errors sections are uniformly typset

In reply to John Snow

Transactions have the only instance of an Errors section that isn't a rST list; turn it into one.

---
 docs/devel/qapi-code-gen.rst | 7 +++++++
 qapi/transaction.json        | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)
docs/devel/qapi-code-gen.rst +7 -0
index f453bd35465..cee43222f19 100644
@@ -1011,6 +1011,13 @@ like this::
 "Returns" and "Errors" sections are only valid for commands.  They
 document the success and the error response, respectively.
 
+"Errors" sections should be formatted as an rST list, each entry
+detailing a relevant error condition. For example::
+
+ # Errors:
+ #     - If @device does not exist, DeviceNotFound
+ #     - Any other error returns a GenericError.
+
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
qapi/transaction.json +1 -1
index 5749c133d4a..07afc269d54 100644
@@ -235,7 +235,7 @@
 #     additional detail.
 #
 # Errors:
-#     Any errors from commands in the transaction
+#     - Any errors from commands in the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there
 #     will be information on only one failed operation returned in an
Signature · 1 line
2.44.0
Reviewed-by on v1 8/13
#21 lore raw

Re: [PATCH 08/13] qapi: ensure all errors sections are uniformly typset

Quoted 4 lines · John Snow

Transactions have the only instance of an Errors section that isn't a rST list; turn it into one.

Let;s explain the "why" a bit more clearly. Maybe

qapi: Nail down convention that Errors sections are lists

By unstated convention, Errors sections are rST lists. Document the convention, and make the one exception conform.

Quoted 28 lines
---
 docs/devel/qapi-code-gen.rst | 7 +++++++
 qapi/transaction.json        | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)
docs/devel/qapi-code-gen.rst +7 -0
index f453bd35465..cee43222f19 100644
@@ -1011,6 +1011,13 @@ like this::
 "Returns" and "Errors" sections are only valid for commands.  They
 document the success and the error response, respectively.
 
+"Errors" sections should be formatted as an rST list, each entry
+detailing a relevant error condition. For example::
+
+ # Errors:
+ #     - If @device does not exist, DeviceNotFound
+ #     - Any other error returns a GenericError.
+
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
qapi/transaction.json +0 -0
index 5749c133d4a..07afc269d54 100644

qapi/transaction.json line 241

Quoted 8 lines
qapi/transaction.json +1 -1
@@ -235,7 +235,7 @@
 #     additional detail.
 #
 # Errors:
-#     Any errors from commands in the transaction
+#     - Any errors from commands in the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there
 #     will be information on only one failed operation returned in an

Preferably with an improved commit message

author
#22 lore raw

Re: [PATCH 08/13] qapi: ensure all errors sections are uniformly typset

Quoted 52 lines · Markus Armbruster
Quoted 4 lines · John Snow

Transactions have the only instance of an Errors section that isn't a rST list; turn it into one.

Let;s explain the "why" a bit more clearly. Maybe

qapi: Nail down convention that Errors sections are lists

By unstated convention, Errors sections are rST lists. Document the convention, and make the one exception conform.

Quoted 28 lines
---
 docs/devel/qapi-code-gen.rst | 7 +++++++
 qapi/transaction.json        | 2 +-
 2 files changed, 8 insertions(+), 1 deletion(-)
docs/devel/qapi-code-gen.rst +7 -0
index f453bd35465..cee43222f19 100644
@@ -1011,6 +1011,13 @@ like this::
 "Returns" and "Errors" sections are only valid for commands.  They
 document the success and the error response, respectively.
 
+"Errors" sections should be formatted as an rST list, each entry
+detailing a relevant error condition. For example::
+
+ # Errors:
+ #     - If @device does not exist, DeviceNotFound
+ #     - Any other error returns a GenericError.
+
 A "Since: x.y.z" tagged section lists the release that introduced the
 definition.
 
qapi/transaction.json +0 -0
index 5749c133d4a..07afc269d54 100644

qapi/transaction.json line 241

Quoted 8 lines
qapi/transaction.json +1 -1
@@ -235,7 +235,7 @@
 #     additional detail.
 #
 # Errors:
-#     Any errors from commands in the transaction
+#     - Any errors from commands in the transaction
 #
 # Note: The transaction aborts on the first failure.  Therefore, there
 #     will be information on only one failed operation returned in an

Preferably with an improved commit message

Quoted 2 lines

okie dokie.

(Feel free to adjust the doc phrasing too, if you want. I promise I'm not offended by that.)

Quoted 1 line
author
#23 lore raw

PATCH 9/13 qapi: convert "Note" sections to plain rST

In reply to John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

---
 docs/devel/qapi-code-gen.rst                  |  7 +-
 qapi/block-core.json                          | 28 +++---
 qapi/block.json                               |  2 +-
 qapi/char.json                                | 12 +--
 qapi/control.json                             | 17 ++--
 qapi/dump.json                                |  2 +-
 qapi/introspect.json                          |  6 +-
 qapi/machine-target.json                      | 26 +++---
 qapi/machine.json                             | 47 +++++-----
 qapi/migration.json                           | 12 +--
 qapi/misc.json                                | 88 +++++++++----------
 qapi/net.json                                 |  6 +-
 qapi/pci.json                                 |  7 +-
 qapi/qdev.json                                | 28 +++---
 qapi/qom.json                                 | 19 ++--
 qapi/rocker.json                              | 16 ++--
 qapi/run-state.json                           | 18 ++--
 qapi/sockets.json                             | 10 +--
 qapi/stats.json                               | 22 ++---
 qapi/transaction.json                         |  8 +-
 qapi/ui.json                                  | 29 +++---
 qapi/virtio.json                              | 12 +--
 qga/qapi-schema.json                          | 48 +++++-----
 scripts/qapi/parser.py                        | 15 ++++
 tests/qapi-schema/doc-empty-section.err       |  2 +-
 tests/qapi-schema/doc-empty-section.json      |  2 +-
 tests/qapi-schema/doc-good.json               |  6 +-
 tests/qapi-schema/doc-good.out                | 10 ++-
 tests/qapi-schema/doc-good.txt                | 14 ++-
 .../qapi-schema/doc-interleaved-section.json  |  2 +-
 30 files changed, 266 insertions(+), 255 deletions(-)
docs/devel/qapi-code-gen.rst +3 -4
index cee43222f19..ae97b335cbf 100644
@@ -995,14 +995,13 @@ line "Features:", like this::
   # @feature: Description text
 
 A tagged section begins with a paragraph that starts with one of the
-following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:",
-"Returns:", "Errors:", "TODO:".  It ends with the start of a new
-section.
+following words: "Since:", "Example:"/"Examples:", "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::
 
- # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco
+ # TODO: Ut enim ad minim veniam, quis nostrud exercitation ullamco
  #     laboris nisi ut aliquip ex ea commodo consequat.
  #
  #     Duis aute irure dolor in reprehenderit in voluptate velit esse
qapi/block-core.json +14 -14
index df5e07debd2..cacedfb771c 100644
@@ -1619,9 +1619,9 @@
 #
 # @unstable: Member @x-perf is experimental.
 #
-# Note: @on-source-error and @on-target-error only affect background
-#     I/O.  If an error occurs during a guest write request, the
-#     device's rerror/werror actions will be used.
+# .. note:: @on-source-error and @on-target-error only affect background
+#    I/O.  If an error occurs during a guest write request, the device's
+#    rerror/werror actions will be used.
 #
 # Since: 4.2
 ##
@@ -5545,8 +5545,8 @@
 #     after this event and must be repaired (Since 2.2; before, every
 #     BLOCK_IMAGE_CORRUPTED event was fatal)
 #
-# Note: If action is "stop", a STOP event will eventually follow the
-#     BLOCK_IO_ERROR event.
+# .. note:: If action is "stop", a STOP event will eventually follow the
+#    BLOCK_IO_ERROR event.
 #
 # Example:
 #
@@ -5592,8 +5592,8 @@
 #     field is a debugging aid for humans, it should not be parsed by
 #     applications) (since: 2.2)
 #
-# Note: If action is "stop", a STOP event will eventually follow the
-#     BLOCK_IO_ERROR event
+# .. note:: If action is "stop", a STOP event will eventually follow the
+#    BLOCK_IO_ERROR event.
 #
 # Since: 0.13
 #
@@ -5731,8 +5731,8 @@
 #
 # @speed: rate limit, bytes per second
 #
-# Note: The "ready to complete" status is always reset by a
-#     @BLOCK_JOB_ERROR event
+# .. note:: The "ready to complete" status is always reset by a
+#    @BLOCK_JOB_ERROR event.
 #
 # Since: 1.3
 #
@@ -5985,7 +5985,7 @@
 #
 # @sectors-count: failed read operation sector count
 #
-# Note: This event is rate-limited.
+# .. note:: This event is rate-limited.
 #
 # Since: 2.0
 #
@@ -6016,7 +6016,7 @@
 #
 # @sectors-count: failed read operation sector count
 #
-# Note: This event is rate-limited.
+# .. note:: This event is rate-limited.
 #
 # Since: 2.0
 #
@@ -6048,9 +6048,9 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# Notes: In transaction, if @name is empty, or any snapshot matching
-#     @name exists, the operation will fail.  Only some image formats
-#     support it, for example, qcow2, and rbd.
+# .. note:: In transaction, if @name is empty, or any snapshot matching
+#    @name exists, the operation will fail.  Only some image formats
+#    support it, for example, qcow2, and rbd.
 #
 # Since: 1.7
 ##
qapi/block.json +1 -1
index 5de99fe09d9..ea81d9e1921 100644
@@ -113,7 +113,7 @@
 # Errors:
 #     - If @device is not a valid block device, DeviceNotFound
 #
-# Notes: Ejecting a device with no media results in success
+# .. note:: Ejecting a device with no media results in success.
 #
 # Since: 0.14
 #
qapi/char.json +6 -6
index 777dde55d97..5eabf8e7645 100644
@@ -21,8 +21,8 @@
 #     backend (e.g. with the chardev=... option) is in open or closed
 #     state (since 2.1)
 #
-# Notes: @filename is encoded using the QEMU command line character
-#     device encoding.  See the QEMU man page for details.
+# .. note:: @filename is encoded using the QEMU command line character
+#    device encoding.  See the QEMU man page for details.
 #
 # Since: 0.14
 ##
@@ -388,9 +388,9 @@
 #
 # @rows: console height, in chars
 #
-# Note: the options are only effective when the VNC or SDL graphical
-#     display backend is active.  They are ignored with the GTK,
-#     Spice, VNC and D-Bus display backends.
+# .. note:: The options are only effective when the VNC or SDL graphical
+#    display backend is active.  They are ignored with the GTK, Spice,
+#    VNC and D-Bus display backends.
 #
 # Since: 1.5
 ##
@@ -806,7 +806,7 @@
 #
 # @open: true if the guest has opened the virtio-serial port
 #
-# Note: This event is rate-limited.
+# .. note:: This event is rate-limited.
 #
 # Since: 2.1
 #
qapi/control.json +8 -9
index 10c906fa0e7..59d5e00c151 100644
@@ -22,14 +22,13 @@
 #          "arguments": { "enable": [ "oob" ] } }
 #     <- { "return": {} }
 #
-# Notes: This command is valid exactly when first connecting: it must
-#     be issued before any other command will be accepted, and will
-#     fail once the monitor is accepting other commands.  (see qemu
-#     docs/interop/qmp-spec.rst)
+# .. note:: This command is valid exactly when first connecting: it must
+#    be issued before any other command will be accepted, and will fail
+#    once the monitor is accepting other commands.  (see qemu
+#    docs/interop/qmp-spec.rst)
 #
-#     The QMP client needs to explicitly enable QMP capabilities,
-#     otherwise all the QMP capabilities will be turned off by
-#     default.
+# .. note:: The QMP client needs to explicitly enable QMP capabilities,
+#    otherwise all the QMP capabilities will be turned off by default.
 #
 # Since: 0.13
 ##
@@ -150,8 +149,8 @@
 #          ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.
+#
 ##
 { 'command': 'query-commands', 'returns': ['CommandInfo'],
   'allow-preconfig': true }
qapi/dump.json +1 -1
index 2fa9504d864..f9aee7ea1dd 100644
@@ -90,7 +90,7 @@
 #     and @length is not allowed to be specified with non-elf @format
 #     at the same time (since 2.0)
 #
-# Note: All boolean arguments default to false
+# .. note:: All boolean arguments default to false.
 #
 # Since: 1.2
 #
qapi/introspect.json +3 -3
index b041b02ba8c..b15052ec21a 100644
@@ -41,9 +41,9 @@
 #     names are guaranteed to be unique (no name will be duplicated
 #     with different meta-types).
 #
-# Note: the QAPI schema is also used to help define *internal*
-#     interfaces, by defining QAPI types.  These are not part of the
-#     QMP wire ABI, and therefore not returned by this command.
+# .. note:: The QAPI schema is also used to help define *internal*
+#    interfaces, by defining QAPI types.  These are not part of the QMP
+#    wire ABI, and therefore not returned by this command.
 #
 # Since: 2.5
 ##
qapi/machine-target.json +13 -13
index 29428530923..a8d9ec87f59 100644
@@ -49,15 +49,15 @@
 #     to be migration-safe, but allows tooling to get an insight and
 #     work with model details.
 #
-# Note: When a non-migration-safe CPU model is expanded in static
-#     mode, some features enabled by the CPU model may be omitted,
-#     because they can't be implemented by a static CPU model
-#     definition (e.g. cache info passthrough and PMU passthrough in
-#     x86). If you need an accurate representation of the features
-#     enabled by a non-migration-safe CPU model, use @full.  If you
-#     need a static representation that will keep ABI compatibility
-#     even when changing QEMU version or machine-type, use @static
-#     (but keep in mind that some features may be omitted).
+# .. note:: When a non-migration-safe CPU model is expanded in static
+#    mode, some features enabled by the CPU model may be omitted,
+#    because they can't be implemented by a static CPU model definition
+#    (e.g. cache info passthrough and PMU passthrough in x86). If you
+#    need an accurate representation of the features enabled by a
+#    non-migration-safe CPU model, use @full.  If you need a static
+#    representation that will keep ABI compatibility even when changing
+#    QEMU version or machine-type, use @static (but keep in mind that
+#    some features may be omitted).
 #
 # Since: 2.8
 ##
@@ -175,8 +175,8 @@
 #     - if a model contains an unknown cpu definition name, unknown
 #       properties or properties with wrong types.
 #
-# Note: this command isn't specific to s390x, but is only implemented
-#     on this architecture currently.
+# .. note:: This command isn't specific to s390x, but is only
+#    implemented on this architecture currently.
 #
 # Since: 2.8
 ##
@@ -229,8 +229,8 @@
 #     - if a model contains an unknown cpu definition name, unknown
 #       properties or properties with wrong types.
 #
-# Note: this command isn't specific to s390x, but is only implemented
-#     on this architecture currently.
+# .. note:: This command isn't specific to s390x, but is only
+#    implemented on this architecture currently.
 #
 # Since: 2.8
 ##
qapi/machine.json +24 -23

119 lines not on this page · raw message

qapi/migration.json +6 -6
index 7d4b567eb59..85a14bb4308 100644
@@ -1437,8 +1437,8 @@
 #
 # Cancel the current executing migration process.
 #
-# Notes: This command succeeds even if there is no migration process
-#     running.
+# .. note:: This command succeeds even if there is no migration process
+#    running.
 #
 # Since: 0.14
 #
@@ -1570,16 +1570,16 @@
 #
 # Since: 0.14
 #
-# Notes:
+# .. admonition:: Notes
 #
 #     1. The 'query-migrate' command should be used to check
 #        migration's progress and final result (this information is
 #        provided by the 'status' member)
 #
-#     2. All boolean arguments default to false
+#     2. All boolean arguments default to false.
 #
 #     3. The user Monitor's "detach" argument is invalid in QMP and
-#        should not be used
+#        should not be used.
 #
 #     4. The uri argument should have the Uniform Resource Identifier
 #        of default destination VM. This connection will be bound to
@@ -1653,7 +1653,7 @@
 #
 # Since: 2.3
 #
-# Notes:
+# .. admonition:: Notes
 #
 #     1. It's a bad idea to use a string for the uri, but it needs to
 #        stay compatible with -incoming and the format of the uri is
qapi/misc.json +43 -45

157 lines not on this page · raw message

qapi/net.json +3 -3
index c19df435a53..dd6c365c34d 100644
@@ -22,9 +22,9 @@
 #
 # Since: 0.14
 #
-# Notes: Not all network adapters support setting link status.  This
-#     command will succeed even if the network adapter does not
-#     support link status notification.
+# .. note:: Not all network adapters support setting link status.  This
+#    command will succeed even if the network adapter does not support
+#    link status notification.
 #
 # Example:
 #
qapi/pci.json +4 -3
index 08bf6958634..f51159a2c4c 100644
@@ -146,8 +146,8 @@
 #
 # @regions: a list of the PCI I/O regions associated with the device
 #
-# Notes: the contents of @class_info.desc are not stable and should
-#     only be treated as informational.
+# .. note:: The contents of @class_info.desc are not stable and should
+#    only be treated as informational.
 #
 # Since: 0.14
 ##
@@ -311,7 +311,8 @@
 #           ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
+#     Note: This example has been shortened as the real response is too
 #     long.
+#
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }
qapi/qdev.json +14 -14
index facaa0bc6a2..f5b35a814fe 100644
@@ -20,9 +20,9 @@
 # Returns: a list of ObjectPropertyInfo describing a devices
 #     properties
 #
-# Note: objects can create properties at runtime, for example to
-#     describe links between different devices and/or objects.  These
-#     properties are not included in the output of this command.
+# .. note:: Objects can create properties at runtime, for example to
+#    describe links between different devices and/or objects.  These
+#    properties are not included in the output of this command.
 #
 # Since: 1.2
 ##
@@ -51,7 +51,7 @@
 #     supports JSON syntax without the reference counting leak that
 #     broke hot-unplug
 #
-# Notes:
+# .. admonition:: Notes
 #
 #     1. Additional arguments depend on the type.
 #
@@ -60,7 +60,7 @@
 #
 #     3. It's possible to list device properties by running QEMU with
 #        the "-device DEVICE,help" command-line argument, where DEVICE
-#        is the device's name
+#        is the device's name.
 #
 # Example:
 #
@@ -92,15 +92,15 @@
 # Errors:
 #     - If @id is not a valid device, DeviceNotFound
 #
-# Notes: When this command completes, the device may not be removed
-#     from the guest.  Hot removal is an operation that requires guest
-#     cooperation.  This command merely requests that the guest begin
-#     the hot removal process.  Completion of the device removal
-#     process is signaled with a DEVICE_DELETED event.  Guest reset
-#     will automatically complete removal for all devices.  If a
-#     guest-side error in the hot removal process is detected, the
-#     device will not be removed and a DEVICE_UNPLUG_GUEST_ERROR event
-#     is sent.  Some errors cannot be detected.
+# .. note:: When this command completes, the device may not be removed
+#    from the guest.  Hot removal is an operation that requires guest
+#    cooperation.  This command merely requests that the guest begin the
+#    hot removal process.  Completion of the device removal process is
+#    signaled with a DEVICE_DELETED event.  Guest reset will
+#    automatically complete removal for all devices.  If a guest-side
+#    error in the hot removal process is detected, the device will not
+#    be removed and a DEVICE_UNPLUG_GUEST_ERROR event is sent.  Some
+#    errors cannot be detected.
 #
 # Since: 0.14
 #
qapi/qom.json +9 -10
index 8bd299265e3..5bfa0ded42c 100644
@@ -195,12 +195,12 @@
 #
 # @typename: the type name of an object
 #
-# Note: objects can create properties at runtime, for example to
-#     describe links between different devices and/or objects.  These
-#     properties are not included in the output of this command.
-#
 # Returns: a list of ObjectPropertyInfo describing object properties
 #
+# .. note:: Objects can create properties at runtime, for example to
+#    describe links between different devices and/or objects.  These
+#    properties are not included in the output of this command.
+#
 # Since: 2.12
 ##
 { 'command': 'qom-list-properties',
@@ -612,12 +612,11 @@
 #     older to allow migration with newer QEMU versions.
 #     (default: false generally, but true for machine types <= 4.0)
 #
-# Note: prealloc=true and reserve=false cannot be set at the same
-#     time.  With reserve=true, the behavior depends on the operating
-#     system: for example, Linux will not reserve swap space for
-#     shared file mappings -- "not applicable". In contrast,
-#     reserve=false will bail out if it cannot be configured
-#     accordingly.
+# .. note:: prealloc=true and reserve=false cannot be set at the same
+#    time.  With reserve=true, the behavior depends on the operating
+#    system: for example, Linux will not reserve swap space for shared
+#    file mappings -- "not applicable". In contrast, reserve=false will
+#    bail out if it cannot be configured accordingly.
 #
 # Since: 2.1
 ##
qapi/rocker.json +8 -8
index f5225eb62cc..9f95e638309 100644
@@ -138,8 +138,8 @@
 #
 # @ip-dst: IP header destination address
 #
-# Note: optional members may or may not appear in the flow key
-#     depending if they're relevant to the flow key.
+# .. note:: Optional members may or may not appear in the flow key
+#    depending if they're relevant to the flow key.
 #
 # Since: 2.4
 ##
@@ -168,8 +168,8 @@
 #
 # @ip-tos: IP header TOS field
 #
-# Note: optional members may or may not appear in the flow mask
-#     depending if they're relevant to the flow mask.
+# .. note:: Optional members may or may not appear in the flow mask
+#    depending if they're relevant to the flow mask.
 #
 # Since: 2.4
 ##
@@ -195,8 +195,8 @@
 #
 # @out-pport: physical output port
 #
-# Note: optional members may or may not appear in the flow action
-#     depending if they're relevant to the flow action.
+# .. note:: Optional members may or may not appear in the flow action
+#    depending if they're relevant to the flow action.
 #
 # Since: 2.4
 ##
@@ -288,8 +288,8 @@
 #
 # @ttl-check: perform TTL check
 #
-# Note: optional members may or may not appear in the group depending
-#     if they're relevant to the group type.
+# .. note:: Optional members may or may not appear in the group depending
+#    if they're relevant to the group type.
 #
 # Since: 2.4
 ##
qapi/run-state.json +9 -9
index f8773f23b29..dc524234ace 100644
@@ -146,9 +146,9 @@
 # @reason: The @ShutdownCause which resulted in the SHUTDOWN.
 #     (since 4.0)
 #
-# Note: If the command-line option "-no-shutdown" has been specified,
-#     qemu will not exit, and a STOP event will eventually follow the
-#     SHUTDOWN event
+# .. note:: If the command-line option "-no-shutdown" has been
+#    specified, qemu will not exit, and a STOP event will eventually
+#    follow the SHUTDOWN event.
 #
 # Since: 0.12
 #
@@ -247,8 +247,8 @@
 # saved on disk, for example, S4 state, which is sometimes called
 # hibernate state
 #
-# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering
-#     this state
+# .. note:: QEMU shuts down (similar to event @SHUTDOWN) when entering
+#    this state.
 #
 # Since: 1.2
 #
@@ -281,11 +281,11 @@
 #
 # @action: action that has been taken
 #
-# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG
-#     event is followed respectively by the RESET, SHUTDOWN, or STOP
-#     events
+# .. note:: If action is "reset", "shutdown", or "pause" the WATCHDOG
+#    event is followed respectively by the RESET, SHUTDOWN, or STOP
+#    events.
 #
-# Note: This event is rate-limited.
+# .. note:: This event is rate-limited.
 #
 # Since: 0.13
 #
qapi/sockets.json +5 -5
index aa97c897687..20e05ca7ac2 100644
@@ -104,8 +104,8 @@
 #
 # @port: port
 #
-# Note: string types are used to allow for possible future hostname or
-#     service resolution support.
+# .. note:: string types are used to allow for possible future hostname
+#    or service resolution support.
 #
 # Since: 2.8
 ##
@@ -179,9 +179,9 @@
 #
 # @type: Transport type
 #
-# Note: This type is deprecated in favor of SocketAddress.  The
-#     difference between SocketAddressLegacy and SocketAddress is that
-#     the latter has fewer {} on the wire.
+# .. note:: This type is deprecated in favor of SocketAddress.  The
+#    difference between SocketAddressLegacy and SocketAddress is that
+#    the latter has fewer {} on the wire.
 #
 # Since: 1.3
 ##
qapi/stats.json +11 -11
index 578b52c7ef7..d5ffe32d057 100644
@@ -258,17 +258,17 @@
 #
 # @provider: a provider to restrict the query to.
 #
-# Note: runtime-collected statistics and their names fall outside
-#     QEMU's usual deprecation policies.  QEMU will try to keep the
-#     set of available data stable, together with their names, but
-#     will not guarantee stability at all costs; the same is true of
-#     providers that source statistics externally, e.g. from Linux.
-#     For example, if the same value is being tracked with different
-#     names on different architectures or by different providers, one
-#     of them might be renamed.  A statistic might go away if an
-#     algorithm is changed or some code is removed; changing a default
-#     might cause previously useful statistics to always report 0.
-#     Such changes, however, are expected to be rare.
+# .. note:: runtime-collected statistics and their names fall outside
+#    QEMU's usual deprecation policies.  QEMU will try to keep the set
+#    of available data stable, together with their names, but will not
+#    guarantee stability at all costs; the same is true of providers
+#    that source statistics externally, e.g. from Linux.  For example,
+#    if the same value is being tracked with different names on
+#    different architectures or by different providers, one of them
+#    might be renamed.  A statistic might go away if an algorithm is
+#    changed or some code is removed; changing a default might cause
+#    previously useful statistics to always report 0.  Such changes,
+#    however, are expected to be rare.
 #
 # Since: 7.1
 ##
qapi/transaction.json +4 -4
index 07afc269d54..bcb05fdedd6 100644
@@ -237,10 +237,10 @@
 # Errors:
 #     - Any errors from commands in the transaction
 #
-# Note: The transaction aborts on the first failure.  Therefore, there
-#     will be information on only one failed operation returned in an
-#     error condition, and subsequent actions will not have been
-#     attempted.
+# .. note:: The transaction aborts on the first failure.  Therefore,
+#    there will be information on only one failed operation returned in
+#    an error condition, and subsequent actions will not have been
+#    attempted.
 #
 # Since: 1.1
 #
qapi/ui.json +14 -15
index c12f5292571..a1999965e44 100644
@@ -107,11 +107,10 @@
 #     - '+INT' where INT is the number of seconds from now (integer)
 #     - 'INT' where INT is the absolute time in seconds
 #
-# Notes: Time is relative to the server and currently there is no way
-#     to coordinate server time with client time.  It is not
-#     recommended to use the absolute time version of the @time
-#     parameter unless you're sure you are on the same machine as the
-#     QEMU instance.
+# .. note:: Time is relative to the server and currently there is no way
+#    to coordinate server time with client time.  It is not recommended
+#    to use the absolute time version of the @time parameter unless
+#    you're sure you are on the same machine as the QEMU instance.
 #
 # Since: 7.0
 ##
@@ -274,7 +273,7 @@
 # @unknown: No information is available about mouse mode used by the
 #     spice server.
 #
-# Note: spice/enums.h has a SpiceMouseMode already, hence the name.
+# .. note:: spice/enums.h has a SpiceMouseMode already, hence the name.
 #
 # Since: 1.1
 ##
@@ -705,9 +704,9 @@
 #
 # Since: 1.1
 #
-# Notes: An empty password in this command will set the password to
-#     the empty string.  Existing clients are unaffected by executing
-#     this command.
+# .. note:: An empty password in this command will set the password to
+#    the empty string.  Existing clients are unaffected by executing
+#    this command.
 ##
 { 'command': 'change-vnc-password',
   'data': { 'password': 'str' },
@@ -722,8 +721,8 @@
 #
 # @client: client information
 #
-# Note: This event is emitted before any authentication takes place,
-#     thus the authentication ID is not provided
+# .. note:: This event is emitted before any authentication takes place,
+#    thus the authentication ID is not provided.
 #
 # Since: 0.13
 #
@@ -1268,10 +1267,10 @@
 #
 # Since: 2.6
 #
-# Note: The consoles are visible in the qom tree, under
-#     /backend/console[$index]. They have a device link and head
-#     property, so it is possible to map which console belongs to
-#     which device and display.
+# .. note:: The consoles are visible in the qom tree, under
+#    /backend/console[$index]. They have a device link and head
+#    property, so it is possible to map which console belongs to which
+#    device and display.
 #
 # Examples:
 #
qapi/virtio.json +6 -6
index 74fc27c7029..b91f3cdd0df 100644
@@ -559,12 +559,12 @@
 #
 # Returns: VirtQueueStatus of the VirtQueue
 #
-# Notes: last_avail_idx will not be displayed in the case where the
-#     selected VirtIODevice has a running vhost device and the
-#     VirtIODevice VirtQueue index (queue) does not exist for the
-#     corresponding vhost device vhost_virtqueue.  Also,
-#     shadow_avail_idx will not be displayed in the case where the
-#     selected VirtIODevice has a running vhost device.
+# .. note:: last_avail_idx will not be displayed in the case where the
+#    selected VirtIODevice has a running vhost device and the
+#    VirtIODevice VirtQueue index (queue) does not exist for the
+#    corresponding vhost device vhost_virtqueue.  Also, shadow_avail_idx
+#    will not be displayed in the case where the selected VirtIODevice
+#    has a running vhost device.
 #
 # Since: 7.2
 #
qga/qapi-schema.json +24 -24

91 lines not on this page · raw message

scripts/qapi/parser.py +15 -0
index dfd6a6c5bee..53b06a94508 100644
@@ -548,6 +548,21 @@ def get_doc(self) -> 'QAPIDoc':
                         r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
                         line):
                     # tagged section
+
+                    # TODO: Remove this error sometime in 2025 or so
+                    # after we've fully transitioned to the new qapidoc
+                    # generator.
+
+                    # See commit message for more markup suggestions O:-)
+                    if 'Note' in match.group(1):
+                        emsg = (
+                            f"The '{match.group(1)}' section is no longer "
+                            "supported. Please use rST's '.. note::' or "
+                            "'.. admonition:: notes' directives, or another "
+                            "suitable admonition instead."
+                        )
+                        raise QAPIParseError(self, emsg)
+
                     doc.new_tagged_section(self.info, match.group(1))
                     text = line[match.end():]
                     if text:
tests/qapi-schema/doc-empty-section.err +1 -1
index 5f03a6d733f..711a0d629c2 100644
@@ -1 +1 @@
-doc-empty-section.json:6: text required after 'Note:'
+doc-empty-section.json:6: text required after 'Errors:'
tests/qapi-schema/doc-empty-section.json +1 -1
index f3384e9a3bb..f179d3eff6d 100644
@@ -3,6 +3,6 @@
 ##
 # @foo:
 #
-# Note:
+# Errors:
 ##
 { 'command': 'foo', 'data': {'a': 'int'} }
tests/qapi-schema/doc-good.json +3 -3
index 8b39eb946af..4b338cc0186 100644
@@ -29,7 +29,7 @@
 # - Second list
 #   Note: still in list
 #
-# Note: not in list
+# .. note:: not in list
 #
 # 1. Third list
 #    is numbered
@@ -157,7 +157,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Note: @arg3 is undocumented
+# .. note:: @arg3 is undocumented
 #
 # Returns: @Object
 #
@@ -165,7 +165,7 @@
 #
 # TODO: frobnicate
 #
-# Notes:
+# .. admonition:: Notes
 #
 #  - Lorem ipsum dolor sit amet
 #  - Ut enim ad minim veniam
tests/qapi-schema/doc-good.out +6 -4
index 435f6e6d768..2c9b4e419cb 100644
@@ -76,7 +76,7 @@ Not in list
 - Second list
   Note: still in list
 
-Note: not in list
+.. note:: not in list
 
 1. Third list
    is numbered
@@ -169,15 +169,17 @@ description starts on the same line
 a feature
     feature=cmd-feat2
 another feature
-    section=Note
-@arg3 is undocumented
+    section=None
+.. note:: @arg3 is undocumented
     section=Returns
 @Object
     section=Errors
 some
     section=TODO
 frobnicate
-    section=Notes
+    section=None
+.. admonition:: Notes
+
  - Lorem ipsum dolor sit amet
  - Ut enim ad minim veniam
 
tests/qapi-schema/doc-good.txt +6 -8
index 847db70412d..b89f35d5476 100644
@@ -17,7 +17,9 @@ Not in list
 
 * Second list Note: still in list
 
-Note: not in list
+Note:
+
+  not in list
 
 1. Third list is numbered
 
@@ -193,11 +195,9 @@ Features
 "cmd-feat2"
    another feature
 
+Note:
 
-Note
-~~~~
-
-"arg3" is undocumented
+  "arg3" is undocumented
 
 
 Returns
@@ -211,9 +211,7 @@ Errors
 
 some
 
-
-Notes
-~~~~~
+Notes:
 
 * Lorem ipsum dolor sit amet
 
tests/qapi-schema/doc-interleaved-section.json +1 -1
index adb29e98daa..b26bc0bbb79 100644
@@ -10,7 +10,7 @@
 #
 #           bao
 #
-# Note: a section.
+# Returns: a section.
 #
 # @foobar: catch this
 #
Signature · 1 line
2.44.0
#24 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 5 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Quoted 8 lines

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting

Scratch "... ..." and downcase "Update"?

Quoted 44 lines

a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 89 lines
qga/qapi-schema.json +17 -22
index b3de1fb6b3a..57598331c5c 100644
@@ -422,8 +422,9 @@
 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
 #     below)
 #
-# Note: This may fail to properly report the current state as a result
-#     of some other guest processes having issued an fs freeze/thaw.
+# .. note:: This may fail to properly report the current state as a
+#    result of some other guest processes having issued an fs
+#    freeze/thaw.
 #
 # Since: 0.15.0
 ##
@@ -443,9 +444,9 @@
 #
 # Returns: Number of file systems currently frozen.
 #
-# Note: On Windows, the command is implemented with the help of a
-#     Volume Shadow-copy Service DLL helper.  The frozen state is
-#     limited for up to 10 seconds by VSS.
+# .. note:: On Windows, the command is implemented with the help of a
+#    Volume Shadow-copy Service DLL helper.  The frozen state is limited
+#    for up to 10 seconds by VSS.
 #
 # Since: 0.15.0
 ##
@@ -479,10 +480,10 @@
 #
 # Returns: Number of file systems thawed by this call
 #
-# Note: if return value does not match the previous call to
-#     guest-fsfreeze-freeze, this likely means some freezable
-#     filesystems were unfrozen before this call, and that the
-#     filesystem state may have changed before issuing this command.
+# .. note:: If return value does not match the previous call to
+#    guest-fsfreeze-freeze, this likely means some freezable filesystems
+#    were unfrozen before this call, and that the filesystem state may
+#    have changed before issuing this command.
 #
 # Since: 0.15.0
 ##
@@ -560,8 +561,8 @@
 # Errors:
 #     - If suspend to disk is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -596,8 +597,8 @@
 # Errors:
 #     - If suspend to ram is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

qga/qapi-schema.json line 1473

Quoted 10 lines
qga/qapi-schema.json +7 -2
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page for
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or the
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken
Quoted 53 lines
qga/qapi-schema.json +0 -0
 #
 # Since: 2.10
 ##
scripts/qapi/parser.py +15 -0
index dfd6a6c5bee..53b06a94508 100644
@@ -548,6 +548,21 @@ def get_doc(self) -> 'QAPIDoc':
                         r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
                         line):
                     # tagged section
+
+                    # TODO: Remove this error sometime in 2025 or so
+                    # after we've fully transitioned to the new qapidoc
+                    # generator.
+
+                    # See commit message for more markup suggestions O:-)
+                    if 'Note' in match.group(1):
+                        emsg = (
+                            f"The '{match.group(1)}' section is no longer "
+                            "supported. Please use rST's '.. note::' or "
+                            "'.. admonition:: notes' directives, or another "
+                            "suitable admonition instead."
+                        )
+                        raise QAPIParseError(self, emsg)
+
                     doc.new_tagged_section(self.info, match.group(1))
                     text = line[match.end():]
                     if text:
tests/qapi-schema/doc-empty-section.err +1 -1
index 5f03a6d733f..711a0d629c2 100644
@@ -1 +1 @@
-doc-empty-section.json:6: text required after 'Note:'
+doc-empty-section.json:6: text required after 'Errors:'
tests/qapi-schema/doc-empty-section.json +1 -1
index f3384e9a3bb..f179d3eff6d 100644
@@ -3,6 +3,6 @@
 ##
 # @foo:
 #
-# Note:
+# Errors:
 ##
 { 'command': 'foo', 'data': {'a': 'int'} }
tests/qapi-schema/doc-good.json +0 -0
index 8b39eb946af..4b338cc0186 100644

tests/qapi-schema/doc-good.json line 32

Quoted 5 lines
tests/qapi-schema/doc-good.json +1 -1
@@ -29,7 +29,7 @@
 # - Second list
 #   Note: still in list
 #
-# Note: not in list
+# .. note:: not in list

Uh... see [*] below.

Quoted 26 lines
tests/qapi-schema/doc-good.json +2 -2
 #
 # 1. Third list
 #    is numbered
@@ -157,7 +157,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Note: @arg3 is undocumented
+# .. note:: @arg3 is undocumented
 #
 # Returns: @Object
 #
@@ -165,7 +165,7 @@
 #
 # TODO: frobnicate
 #
-# Notes:
+# .. admonition:: Notes
 #
 #  - Lorem ipsum dolor sit amet
 #  - Ut enim ad minim veniam
tests/qapi-schema/doc-good.out +0 -0
index 435f6e6d768..2c9b4e419cb 100644

tests/qapi-schema/doc-good.out Not in list · line 79

Quoted 4 lines
tests/qapi-schema/doc-good.out +0 -1
@@ -76,7 +76,7 @@ Not in list
 - Second list
   Note: still in list
 
-Note: not in list

[*] This demonstrates the "Note: ..." is *not* recognized as a "Note" section before the patch (compare to the change we get for recognized sections below).

Obscure fact: the doc parser recognizes tagged sections *only* in definition documentation. Arguably a misfeature.

Your series makes the misfeature even more obscure, because afterwards, the only tagged section left that could make sense in a free-form doc comment is "TODO". Let's not worry about the misfeature now.

Two sensible solutions:

1. Since the patch converts tagged sections, and this isn't, don't touch it. If you feel you want to mention this in the commit message, go ahead.

2. Touch it anyway. Do mention it in the commit message then.

Quoted 70 lines
tests/qapi-schema/doc-good.out +6 -3
+.. note:: not in list
 
 1. Third list
    is numbered
@@ -169,15 +169,17 @@ description starts on the same line
 a feature
     feature=cmd-feat2
 another feature
-    section=Note
-@arg3 is undocumented
+    section=None
+.. note:: @arg3 is undocumented
     section=Returns
 @Object
     section=Errors
 some
     section=TODO
 frobnicate
-    section=Notes
+    section=None
+.. admonition:: Notes
+
  - Lorem ipsum dolor sit amet
  - Ut enim ad minim veniam
 
tests/qapi-schema/doc-good.txt +6 -8
index 847db70412d..b89f35d5476 100644
@@ -17,7 +17,9 @@ Not in list
 
 * Second list Note: still in list
 
-Note: not in list
+Note:
+
+  not in list
 
 1. Third list is numbered
 
@@ -193,11 +195,9 @@ Features
 "cmd-feat2"
    another feature
 
+Note:
 
-Note
-~~~~
-
-"arg3" is undocumented
+  "arg3" is undocumented
 
 
 Returns
@@ -211,9 +211,7 @@ Errors
 
 some
 
-
-Notes
-~~~~~
+Notes:
 
 * Lorem ipsum dolor sit amet
 
tests/qapi-schema/doc-interleaved-section.json +0 -0
index adb29e98daa..b26bc0bbb79 100644

tests/qapi-schema/doc-interleaved-section.json line 16

Quoted 8 lines
tests/qapi-schema/doc-interleaved-section.json +1 -1
@@ -10,7 +10,7 @@
 #
 #           bao
 #
-# Note: a section.
+# Returns: a section.
 #
 # @foobar: catch this
 #

"Returns:" is only valid for commands, and this is a struct. Let's use "TODO:" instead.

#25 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 4 lines
Quoted 4 lines
qga/qapi-schema.json +0 -0
index b3de1fb6b3a..57598331c5c 100644

[...]

Quoted 42 lines
Quoted 23 lines
qga/qapi-schema.json +3 -9
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

qga/qapi-schema.json line 1473

Quoted 10 lines
qga/qapi-schema.json +7 -2
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page for
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or the
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

Quoted 3 lines
   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken

I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line up with the directive, here "note".

Everywhere else, we indent such lines by 4. Hmm. How terrible would it be not to mess with the alignment?

If we want to use 3 for directives, is it worth pointing out in the commit message?

[...]

author
#26 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 64 lines · Markus Armbruster
Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 4 lines
Quoted 4 lines
qga/qapi-schema.json +0 -0
index b3de1fb6b3a..57598331c5c 100644

[...]

Quoted 17 lines
Quoted 17 lines
qga/qapi-schema.json +2 -4
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
Quoted 8 lines

qga/qapi-schema.json

Quoted 8 lines
qga/qapi-schema.json +3 -5
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page

for

Quoted 17 lines

qga/qapi-schema.json line 1473

Quoted 8 lines
qga/qapi-schema.json +5 -2
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or the
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

Quoted 3 lines
   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken

I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line up with the directive, here "note".

Quoted 8 lines

Everywhere else, we indent such lines by 4. Hmm. How terrible would it be not to mess with the alignment?

If we want to use 3 for directives, is it worth pointing out in the commit message?

[...]

Let me look up some conventions and see what's the most prominent... as well as testing what emacs does by default (or if emacs can be configured to do what we want with in-tree style config. Warning: I am functionally inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your own. I'm sorry.)

I use three myself by force of habit and have some mild reluctance to respin for that reason, but ... guess we ought to be consistent if we can.

(No idea where my habit came from. Maybe it is just because it looks nice to me and no other reason.)

((I have no plans, nor desire, to write any kind of checker to enforce this, though - sorry.))

author
#27 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 84 lines · John Snow
Quoted 65 lines · Markus Armbruster
Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 4 lines
Quoted 4 lines
qga/qapi-schema.json +0 -0
index b3de1fb6b3a..57598331c5c 100644

[...]

Quoted 17 lines
Quoted 17 lines
qga/qapi-schema.json +2 -4
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
Quoted 8 lines

qga/qapi-schema.json

Quoted 8 lines
qga/qapi-schema.json +3 -5
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page

for

Quoted 2 lines

qga/qapi-schema.json line 1469

Quoted 2 lines
qga/qapi-schema.json +2 -0
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or

the

Quoted 15 lines

qga/qapi-schema.json line 1473

Quoted 6 lines
qga/qapi-schema.json +3 -2
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

Quoted 3 lines
   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken

I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line up with the directive, here "note".

Quoted 8 lines

Everywhere else, we indent such lines by 4. Hmm. How terrible would it be not to mess with the alignment?

If we want to use 3 for directives, is it worth pointing out in the commit message?

[...]

Let me look up some conventions and see what's the most prominent... as well as testing what emacs does by default (or if emacs can be configured to do what we want with in-tree style config. Warning: I am functionally inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your own. I'm sorry.)

Quoted 9 lines

I use three myself by force of habit and have some mild reluctance to respin for that reason, but ... guess we ought to be consistent if we can.

(No idea where my habit came from. Maybe it is just because it looks nice to me and no other reason.)

((I have no plans, nor desire, to write any kind of checker to enforce this, though - sorry.))

Sphinx doc uses three spaces:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

... but it warns that it's arbitrary; but it seems common to align with the directive.

*
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes
footnotes require "at least 3" spaces

*
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives
directives are only required to be "indented" but the amount isn't
specified. rst docs use three.

I'm happy with three; I don't believe we need to make it consistent with e.g. our home-spun field list syntax (arguments, features) or with code blocks. I think whatever looks good in the source is fine, and I think three looks good for directives. I don't think we need to require this, but I can mention in the commit message that I chose it for the sake of aesthetics and for parity with what most rST docs appear to use.

Note: emacs behavior for wrapping paragraphs in our QAPI files does not create an indent if there isn't already one. I think convincing emacs to apply rST rules inside of a JSON file we lie and call a Python file might be beyond my ability to do quickly.

The default behavior for my emacs (which I haven't customized very much, if at all) in our source tree for *.rst files is to wrap directive lines with a three space indent.

So, I'm happy saying this is a good way to do it.

--js

#28 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 111 lines · John Snow
Quoted 84 lines · John Snow
Quoted 65 lines · Markus Armbruster
Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 4 lines
Quoted 4 lines
qga/qapi-schema.json +0 -0
index b3de1fb6b3a..57598331c5c 100644

[...]

Quoted 17 lines
Quoted 17 lines
qga/qapi-schema.json +2 -4
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
Quoted 8 lines

qga/qapi-schema.json

Quoted 8 lines
qga/qapi-schema.json +3 -5
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page

for

Quoted 2 lines

qga/qapi-schema.json line 1469

Quoted 2 lines
qga/qapi-schema.json +2 -0
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or

the

Quoted 15 lines

qga/qapi-schema.json line 1473

Quoted 6 lines
qga/qapi-schema.json +3 -2
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

Quoted 3 lines
   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken

I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line up with the directive, here "note".

Quoted 8 lines

Everywhere else, we indent such lines by 4. Hmm. How terrible would it be not to mess with the alignment?

If we want to use 3 for directives, is it worth pointing out in the commit message?

[...]

Let me look up some conventions and see what's the most prominent... as well as testing what emacs does by default (or if emacs can be configured to do what we want with in-tree style config. Warning: I am functionally inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your own. I'm sorry.)

Quoted 9 lines

I use three myself by force of habit and have some mild reluctance to respin for that reason, but ... guess we ought to be consistent if we can.

(No idea where my habit came from. Maybe it is just because it looks nice to me and no other reason.)

((I have no plans, nor desire, to write any kind of checker to enforce this, though - sorry.))

Sphinx doc uses three spaces:
https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

... but it warns that it's arbitrary; but it seems common to align with the directive.

*
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes
footnotes require "at least 3" spaces

*
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives
directives are only required to be "indented" but the amount isn't
specified. rst docs use three.

Quoted 6 lines

I'm happy with three; I don't believe we need to make it consistent with e.g. our home-spun field list syntax (arguments, features) or with code blocks. I think whatever looks good in the source is fine, and I think three looks good for directives. I don't think we need to require this, but I can mention in the commit message that I chose it for the sake of aesthetics and for parity with what most rST docs appear to use.

My reason for four spaces is reducing churn. To see by how much, I redid your change. I found a few more notes that don't start with a capital letter, or don't end with a period.

Anyway, your diffstat:

 30 files changed, 266 insertions(+), 255 deletions(-)

Mine:

 30 files changed, 134 insertions(+), 119 deletions(-)

A fair bit easier to review.

Quoted 4 lines

Note: emacs behavior for wrapping paragraphs in our QAPI files does not create an indent if there isn't already one. I think convincing emacs to apply rST rules inside of a JSON file we lie and call a Python file might be beyond my ability to do quickly.

Permit me a digression...

We have rST in comments.

Python has rST in doc strings.

JSON has neither comments nor doc strings, but since we use it just for the file name extension, that's irrelevant.

Could Emacs help us more if we used Pythony doc strings instead of comments?

End of digression.

Quoted 3 lines

The default behavior for my emacs (which I haven't customized very much, if at all) in our source tree for *.rst files is to wrap directive lines with a three space indent.

Valid point.

Quoted 1 line

So, I'm happy saying this is a good way to do it.

If we decide to tweak indentation, we should do so in a separate patch that does absolutely nothing but tweak indentation.

author
#29 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 136 lines · Markus Armbruster
Quoted 5 lines · John Snow
Quoted 3 lines · John Snow

On Thu, Jun 20, 2024, 9:35 AM Markus Armbruster <[email protected]>

Quoted 14 lines · wrote:
Quoted 14 lines
Quoted 14 lines
Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 4 lines
Quoted 4 lines
qga/qapi-schema.json +0 -0
index b3de1fb6b3a..57598331c5c 100644

[...]

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

qga/qapi-schema.json line 635

Quoted 7 lines
qga/qapi-schema.json +1 -2
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync

command

Quoted 11 lines
Quoted 11 lines
Quoted 11 lines
Quoted 11 lines

qga/qapi-schema.json line 1466

Quoted 11 lines
qga/qapi-schema.json +1 -3
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
-#     definition specified in os-release(5). Refer to the manual

page

Quoted 7 lines
Quoted 7 lines
Quoted 7 lines
Quoted 7 lines

qga/qapi-schema.json

Quoted 7 lines
qga/qapi-schema.json +3 -4
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual

page

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

for

Quoted 1 line
Quoted 1 line
qga/qapi-schema.json +1 -0
+#    exact description of the fields.  Their values are taken from

the

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines
Quoted 1 line

qga/qapi-schema.json line 1469

Quoted 1 line
qga/qapi-schema.json +1 -0
+#    os-release file.  If the file is not present in the system, or

the

Quoted 1 line
Quoted 1 line
qga/qapi-schema.json +1 -0
+#    values are not present in the file, the fields are not

included.

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

qga/qapi-schema.json line 1472

Quoted 2 lines
qga/qapi-schema.json +0 -1
 #
-#     On Windows the values are filled from information gathered

from

Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines

qga/qapi-schema.json line 1472

Quoted 2 lines
qga/qapi-schema.json +1 -1
-#     the system.
+#    On Windows the values are filled from information gathered

from

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 4 lines

qga/qapi-schema.json line 1473

Quoted 1 line
qga/qapi-schema.json +1 -0
+#    the system.

Please don't change the indentation here. I get the same output with

Quoted 8 lines
Quoted 8 lines
Quoted 8 lines
Quoted 8 lines

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,
# @version, @version-id, @variant and @variant-id follow the
# definition specified in os-release(5). Refer to the manual

page

Quoted 4 lines
Quoted 4 lines
Quoted 4 lines
Quoted 1 line

# for exact description of the fields. Their values are taken

I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line

up

Quoted 3 lines
Quoted 3 lines
Quoted 3 lines

with the directive, here "note".

Everywhere else, we indent such lines by 4. Hmm. How terrible would

it

Quoted 10 lines
Quoted 10 lines
Quoted 7 lines

be not to mess with the alignment?

If we want to use 3 for directives, is it worth pointing out in the commit message?

[...]

Let me look up some conventions and see what's the most prominent... as well as testing what emacs does by default (or if emacs can be

configured

Quoted 2 lines
Quoted 2 lines

to do what we want with in-tree style config. Warning: I am functionally inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on

your

Quoted 4 lines
Quoted 4 lines

own. I'm sorry.)

I use three myself by force of habit and have some mild reluctance to respin for that reason, but ... guess we ought to be consistent if we

can.

Quoted 2 lines
Quoted 2 lines

(No idea where my habit came from. Maybe it is just because it looks

nice

Quoted 8 lines
Quoted 5 lines

to me and no other reason.)

((I have no plans, nor desire, to write any kind of checker to enforce this, though - sorry.))

Sphinx doc uses three spaces:

https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

Quoted 2 lines

... but it warns that it's arbitrary; but it seems common to align with

the

Quoted 4 lines

directive.

*

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes

Quoted 4 lines

footnotes require "at least 3" spaces

*

https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives

Quoted 7 lines

directives are only required to be "indented" but the amount isn't
specified. rst docs use three.

I'm happy with three; I don't believe we need to make it consistent with e.g. our home-spun field list syntax (arguments, features) or with code blocks. I think whatever looks good in the source is fine, and I think three looks good for directives. I don't think we need to require this,

Quoted 8 lines

but

Quoted 2 lines

I can mention in the commit message that I chose it for the sake of aesthetics and for parity with what most rST docs appear to use.

My reason for four spaces is reducing churn. To see by how much, I redid your change. I found a few more notes that don't start with a capital letter, or don't end with a period.

^ Guess I'll re-audit for v2. Hang on to the list of cases you found.

(Sorry for the churn, though. I obviously don't mind it as much as you do, but I suspect I'm a lot less nimble with fiddling through git history than you are and find the value of avoiding churn to be ... lower than you do, in general. Respecting reviewer time is a strong argument, I apologize that some non-mechanical changes snuck into the patch. The downside of hacking together a very large series.)

Quoted 20 lines

Anyway, your diffstat:

 30 files changed, 266 insertions(+), 255 deletions(-)

Mine:

 30 files changed, 134 insertions(+), 119 deletions(-)

A fair bit easier to review.

Quoted 4 lines

Note: emacs behavior for wrapping paragraphs in our QAPI files does not create an indent if there isn't already one. I think convincing emacs to apply rST rules inside of a JSON file we lie and call a Python file might be beyond my ability to do quickly.

Permit me a digression...

We have rST in comments.

Quoted 8 lines

Python has rST in doc strings.

JSON has neither comments nor doc strings, but since we use it just for the file name extension, that's irrelevant.

Could Emacs help us more if we used Pythony doc strings instead of comments?

No idea. Could it? O:-)

(OK, OK, let me see...)

No, apparently not.

Quoted 6 lines

End of digression.

Quoted 1 line

The default behavior for my emacs (which I haven't customized very much,

if

Quoted 1 line

at all) in our source tree for *.rst files is to wrap directive lines

with

Quoted 9 lines
Quoted 1 line

a three space indent.

Valid point.

Quoted 1 line

So, I'm happy saying this is a good way to do it.

If we decide to tweak indentation, we should do so in a separate patch that does absolutely nothing but tweak indentation.

I'd rather not spend all my time undoing and then redoing this patch for the benefit of burying git history behind *two* mass-change patches, please...

#30 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 1 line · John Snow

On Fri, Jun 21, 2024 at 8:23 AM Markus Armbruster <[email protected]> wrote:

[...]

Quoted 6 lines
Quoted 4 lines

My reason for four spaces is reducing churn. To see by how much, I redid your change. I found a few more notes that don't start with a capital letter, or don't end with a period.

^ Guess I'll re-audit for v2. Hang on to the list of cases you found.

Happy to share my patch.

Quoted 6 lines

(Sorry for the churn, though. I obviously don't mind it as much as you do, but I suspect I'm a lot less nimble with fiddling through git history than you are and find the value of avoiding churn to be ... lower than you do, in general. Respecting reviewer time is a strong argument, I apologize that some non-mechanical changes snuck into the patch. The downside of hacking together a very large series.)

You did a good job splitting it up. Minor mistakes are bound to happen. Got to give the reviewer soemthing to find ;)

[...]

author
#31 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

In reply to Markus Armbruster
Quoted 284 lines · Markus Armbruster
Quoted 5 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Quoted 8 lines

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting

Scratch "... ..." and downcase "Update"?

Quoted 11 lines

a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions

Quoted 33 lines

for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 89 lines
qga/qapi-schema.json +17 -22
index b3de1fb6b3a..57598331c5c 100644
@@ -422,8 +422,9 @@
 # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
 #     below)
 #
-# Note: This may fail to properly report the current state as a result
-#     of some other guest processes having issued an fs freeze/thaw.
+# .. note:: This may fail to properly report the current state as a
+#    result of some other guest processes having issued an fs
+#    freeze/thaw.
 #
 # Since: 0.15.0
 ##
@@ -443,9 +444,9 @@
 #
 # Returns: Number of file systems currently frozen.
 #
-# Note: On Windows, the command is implemented with the help of a
-#     Volume Shadow-copy Service DLL helper.  The frozen state is
-#     limited for up to 10 seconds by VSS.
+# .. note:: On Windows, the command is implemented with the help of a
+#    Volume Shadow-copy Service DLL helper.  The frozen state is limited
+#    for up to 10 seconds by VSS.
 #
 # Since: 0.15.0
 ##
@@ -479,10 +480,10 @@
 #
 # Returns: Number of file systems thawed by this call
 #
-# Note: if return value does not match the previous call to
-#     guest-fsfreeze-freeze, this likely means some freezable
-#     filesystems were unfrozen before this call, and that the
-#     filesystem state may have changed before issuing this command.
+# .. note:: If return value does not match the previous call to
+#    guest-fsfreeze-freeze, this likely means some freezable filesystems
+#    were unfrozen before this call, and that the filesystem state may
+#    have changed before issuing this command.
 #
 # Since: 0.15.0
 ##
@@ -560,8 +561,8 @@
 # Errors:
 #     - If suspend to disk is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -596,8 +597,8 @@
 # Errors:
 #     - If suspend to ram is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -631,8 +632,8 @@
 # Errors:
 #     - If hybrid suspend is not supported, Unsupported
 #
-# Notes: It's strongly recommended to issue the guest-sync command
-#     before sending commands when the guest resumes
+# .. note:: It's strongly recommended to issue the guest-sync command
+#    before sending commands when the guest resumes.
 #
 # Since: 1.1
 ##
@@ -1461,16 +1462,15 @@
 #     * POSIX: as defined by os-release(5)
 #     * Windows: contains string "server" or "client"
 #
-# Notes: On POSIX systems the fields @id, @name, @pretty-name,
-#     @version, @version-id, @variant and @variant-id follow the
-#     definition specified in os-release(5). Refer to the manual page
-#     for exact description of the fields.  Their values are taken
-#     from the os-release file.  If the file is not present in the
-#     system, or the values are not present in the file, the fields
-#     are not included.
+# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

qga/qapi-schema.json line 1473

Quoted 10 lines
qga/qapi-schema.json +7 -2
+#    @version, @version-id, @variant and @variant-id follow the
+#    definition specified in os-release(5). Refer to the manual page for
+#    exact description of the fields.  Their values are taken from the
+#    os-release file.  If the file is not present in the system, or the
+#    values are not present in the file, the fields are not included.
 #
-#     On Windows the values are filled from information gathered from
-#     the system.
+#    On Windows the values are filled from information gathered from
+#    the system.

Please don't change the indentation here. I get the same output with

@@ -1461,7 +1462,7 @@
# * POSIX: as defined by os-release(5)
# * Windows: contains string "server" or "client"
#
-# Notes: On POSIX systems the fields @id, @name, @pretty-name, +# .. note:: On POSIX systems the fields @id, @name, @pretty-name,

   #     @version, @version-id, @variant and @variant-id follow the
   #     definition specified in os-release(5). Refer to the manual page
   #     for exact description of the fields.  Their values are taken

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 548

Quoted 9 lines
qga/qapi-schema.json +0 -0
 #
 # Since: 2.10
 ##
scripts/qapi/parser.py +0 -0
index dfd6a6c5bee..53b06a94508 100644
@@ -548,6 +548,21 @@ def get_doc(self) -> 'QAPIDoc':
                         r'(Returns|Errors|Since|Notes?|Examples?|TODO):

*',

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc':

Quoted 8 lines
scripts/qapi/parser.py +6 -0
                         line):
                     # tagged section
+
+                    # TODO: Remove this error sometime in 2025 or so
+                    # after we've fully transitioned to the new qapidoc
+                    # generator.
+
+                    # See commit message for more markup suggestions

O:-)

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc':

Quoted 3 lines
scripts/qapi/parser.py +3 -0
+                    if 'Note' in match.group(1):
+                        emsg = (
+                            f"The '{match.group(1)}' section is no

longer "

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 560

Quoted 1 line
scripts/qapi/parser.py +1 -0
+                            "supported. Please use rST's '.. note::' or

"

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 561

Quoted 1 line
scripts/qapi/parser.py +1 -0
+                            "'.. admonition:: notes' directives, or

another "

Review

Quoted 8 lines
scripts/qapi/parser.py +4 -0
+                            "suitable admonition instead."
+                        )
+                        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-empty-section.err

Review

Quoted 7 lines

index 5f03a6d733f..711a0d629c2 100644

tests/qapi-schema/doc-empty-section.err +1 -1
@@ -1 +1 @@
-doc-empty-section.json:6: text required after 'Note:'
+doc-empty-section.json:6: text required after 'Errors:'
(quoted diff) +0 -0

b/tests/qapi-schema/doc-empty-section.json

Review

Quoted 12 lines

index f3384e9a3bb..f179d3eff6d 100644

tests/qapi-schema/doc-empty-section.json +1 -1
@@ -3,6 +3,6 @@
 ##
 # @foo:
 #
-# Note:
+# Errors:
 ##
 { 'command': 'foo', 'data': {'a': 'int'} }
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.json

tests/qapi-schema/doc-good.json line 32

Quoted 9 lines

index 8b39eb946af..4b338cc0186 100644

tests/qapi-schema/doc-good.json +1 -1
@@ -29,7 +29,7 @@
 # - Second list
 #   Note: still in list
 #
-# Note: not in list
+# .. note:: not in list

Uh... see [*] below.

Review

Quoted 22 lines
tests/qapi-schema/doc-good.json +2 -2
 #
 # 1. Third list
 #    is numbered
@@ -157,7 +157,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Note: @arg3 is undocumented
+# .. note:: @arg3 is undocumented
 #
 # Returns: @Object
 #
@@ -165,7 +165,7 @@
 #
 # TODO: frobnicate
 #
-# Notes:
+# .. admonition:: Notes
 #
 #  - Lorem ipsum dolor sit amet
 #  - Ut enim ad minim veniam
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.out

tests/qapi-schema/doc-good.out Not in list · line 79

Quoted 8 lines

index 435f6e6d768..2c9b4e419cb 100644

tests/qapi-schema/doc-good.out +0 -1
@@ -76,7 +76,7 @@ Not in list
 - Second list
   Note: still in list
 
-Note: not in list

[*] This demonstrates the "Note: ..." is *not* recognized as a "Note" section before the patch (compare to the change we get for recognized sections below).

Quoted 7 lines

Obscure fact: the doc parser recognizes tagged sections *only* in definition documentation. Arguably a misfeature.

Your series makes the misfeature even more obscure, because afterwards, the only tagged section left that could make sense in a free-form doc comment is "TODO". Let's not worry about the misfeature now.

Right, it's gonna go away or be heavily reduced. A fish for another fry.

Quoted 6 lines

Two sensible solutions:

1. Since the patch converts tagged sections, and this isn't, don't touch it. If you feel you want to mention this in the commit message, go ahead.

Oh, uh. Alright. I wonder why I changed it then. I thought I was playing error message whackamole with this one, but maybe I did do a regexp at some point.

I'll leave it be if I can. If I can't, for some reason, then ...

Quoted 2 lines

2. Touch it anyway. Do mention it in the commit message then.

... This, with why I couldn't leave it be.

Quoted 68 lines

Review

Quoted 26 lines
tests/qapi-schema/doc-good.out +6 -3
+.. note:: not in list
 
 1. Third list
    is numbered
@@ -169,15 +169,17 @@ description starts on the same line
 a feature
     feature=cmd-feat2
 another feature
-    section=Note
-@arg3 is undocumented
+    section=None
+.. note:: @arg3 is undocumented
     section=Returns
 @Object
     section=Errors
 some
     section=TODO
 frobnicate
-    section=Notes
+    section=None
+.. admonition:: Notes
+
  - Lorem ipsum dolor sit amet
  - Ut enim ad minim veniam
 
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.txt

Review

Quoted 40 lines

index 847db70412d..b89f35d5476 100644

tests/qapi-schema/doc-good.txt +6 -8
@@ -17,7 +17,9 @@ Not in list
 
 * Second list Note: still in list
 
-Note: not in list
+Note:
+
+  not in list
 
 1. Third list is numbered
 
@@ -193,11 +195,9 @@ Features
 "cmd-feat2"
    another feature
 
+Note:
 
-Note
-~~~~
-
-"arg3" is undocumented
+  "arg3" is undocumented
 
 
 Returns
@@ -211,9 +211,7 @@ Errors
 
 some
 
-
-Notes
-~~~~~
+Notes:
 
 * Lorem ipsum dolor sit amet
 
(quoted diff) +0 -0

b/tests/qapi-schema/doc-interleaved-section.json

Quoted 16 lines

tests/qapi-schema/doc-interleaved-section.json line 16

Quoted 12 lines

index adb29e98daa..b26bc0bbb79 100644

tests/qapi-schema/doc-interleaved-section.json +1 -1
@@ -10,7 +10,7 @@
 #
 #           bao
 #
-# Note: a section.
+# Returns: a section.
 #
 # @foobar: catch this
 #

"Returns:" is only valid for commands, and this is a struct. Let's use "TODO:" instead.

Weird that it didn't prohibit it. Bug?

--js

Quoted 1 line
#32 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 3 lines · John Snow
Quoted 1 line · Markus Armbruster

John Snow <[email protected]> writes:

[...]

Quoted 18 lines
Quoted 8 lines
Quoted 8 lines
tests/qapi-schema/doc-interleaved-section.json +0 -0
index adb29e98daa..b26bc0bbb79 100644
@@ -10,7 +10,7 @@
 #
 #           bao
 #
Quoted 9 lines

tests/qapi-schema/doc-interleaved-section.json line 16

Quoted 5 lines
tests/qapi-schema/doc-interleaved-section.json +1 -1
-# Note: a section.
+# Returns: a section.
 #
 # @foobar: catch this
 #

"Returns:" is only valid for commands, and this is a struct. Let's use "TODO:" instead.

Quoted 1 line

Weird that it didn't prohibit it. Bug?

No: it simply chokes on "description of '@foobar:' follows a section" before it can choke on "'Returns' section is only valid for commands".

#33 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

In reply to John Snow
Quoted 57 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 26 lines
qapi/control.json +6 -7
index 10c906fa0e7..59d5e00c151 100644
@@ -22,14 +22,13 @@
 #          "arguments": { "enable": [ "oob" ] } }
 #     <- { "return": {} }
 #
-# Notes: This command is valid exactly when first connecting: it must
-#     be issued before any other command will be accepted, and will
-#     fail once the monitor is accepting other commands.  (see qemu
-#     docs/interop/qmp-spec.rst)
+# .. note:: This command is valid exactly when first connecting: it must
+#    be issued before any other command will be accepted, and will fail
+#    once the monitor is accepting other commands.  (see qemu
+#    docs/interop/qmp-spec.rst)
 #
-#     The QMP client needs to explicitly enable QMP capabilities,
-#     otherwise all the QMP capabilities will be turned off by
-#     default.
+# .. note:: The QMP client needs to explicitly enable QMP capabilities,
+#    otherwise all the QMP capabilities will be turned off by default.
 #
 # Since: 0.13
 ##

qapi/control.json line 153

Quoted 7 lines
qapi/control.json +2 -2
@@ -150,8 +149,8 @@
 #          ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.
+#

Here's one way to transform the elision note, ...

Quoted 3 lines
qapi/control.json +0 -0
 ##
 { 'command': 'query-commands', 'returns': ['CommandInfo'],
   'allow-preconfig': true }

[...]

Quoted 16 lines
qapi/pci.json +2 -2
index 08bf6958634..f51159a2c4c 100644
@@ -146,8 +146,8 @@
 #
 # @regions: a list of the PCI I/O regions associated with the device
 #
-# Notes: the contents of @class_info.desc are not stable and should
-#     only be treated as informational.
+# .. note:: The contents of @class_info.desc are not stable and should
+#    only be treated as informational.
 #
 # Since: 0.14
 ##

qapi/pci.json line 316

Quoted 7 lines
qapi/pci.json +2 -1
@@ -311,7 +311,8 @@
 #           ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
+#     Note: This example has been shortened as the real response is too
 #     long.
+#

... and here's another way. Same way would be better, wouldn't it? They actually are after PATCH 13:

-# Note: This example has been shortened as the real response is too
-# long.
+# This example has been shortened as the real response is too long.

Move that hunk here, please.

Quoted 2 lines
qapi/pci.json +0 -0
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }

[...]

author
#34 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 136 lines · Markus Armbruster
Quoted 16 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

Quoted 8 lines

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions

Quoted 33 lines

for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 26 lines
qapi/control.json +6 -7
index 10c906fa0e7..59d5e00c151 100644
@@ -22,14 +22,13 @@
 #          "arguments": { "enable": [ "oob" ] } }
 #     <- { "return": {} }
 #
-# Notes: This command is valid exactly when first connecting: it must
-#     be issued before any other command will be accepted, and will
-#     fail once the monitor is accepting other commands.  (see qemu
-#     docs/interop/qmp-spec.rst)
+# .. note:: This command is valid exactly when first connecting: it must
+#    be issued before any other command will be accepted, and will fail
+#    once the monitor is accepting other commands.  (see qemu
+#    docs/interop/qmp-spec.rst)
 #
-#     The QMP client needs to explicitly enable QMP capabilities,
-#     otherwise all the QMP capabilities will be turned off by
-#     default.
+# .. note:: The QMP client needs to explicitly enable QMP capabilities,
+#    otherwise all the QMP capabilities will be turned off by default.
 #
 # Since: 0.13
 ##

qapi/control.json line 153

Quoted 7 lines
qapi/control.json +2 -2
@@ -150,8 +149,8 @@
 #          ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.
+#

Here's one way to transform the elision note, ...

Quoted 3 lines
qapi/control.json +0 -0
 ##
 { 'command': 'query-commands', 'returns': ['CommandInfo'],
   'allow-preconfig': true }

[...]

Quoted 16 lines
qapi/pci.json +2 -2
index 08bf6958634..f51159a2c4c 100644
@@ -146,8 +146,8 @@
 #
 # @regions: a list of the PCI I/O regions associated with the device
 #
-# Notes: the contents of @class_info.desc are not stable and should
-#     only be treated as informational.
+# .. note:: The contents of @class_info.desc are not stable and should
+#    only be treated as informational.
 #
 # Since: 0.14
 ##

qapi/pci.json line 316

Quoted 7 lines
qapi/pci.json +2 -1
@@ -311,7 +311,8 @@
 #           ]
 #        }
 #
-# Note: This example has been shortened as the real response is too
+#     Note: This example has been shortened as the real response is too
 #     long.
+#

... and here's another way. Same way would be better, wouldn't it? They actually are after PATCH 13:

-# Note: This example has been shortened as the real response is too
-# long.
+# This example has been shortened as the real response is too long.

Quoted 7 lines

Move that hunk here, please.

Quoted 2 lines
qapi/pci.json +0 -0
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }

[...]

Apologies, I meant to do this but forgot there were two cases and only nabbed one.

Fixing.

Quoted 1 line
#35 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 4 lines · John Snow

Apologies, I meant to do this but forgot there were two cases and only nabbed one.

Fixing.

No problem at all!

#36 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

In reply to John Snow
Quoted 43 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

Quoted 8 lines

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere,

Not mentioned, and may or may not be worth mentioning: both "Note:" and "Notes:" become ".. note::", which renders as "Note". One instance quoted below.

No objection to the change; you obviously double-checked it reads okay that way.

Quoted 7 lines

with just two "caution"
directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 4 lines
qapi/block-core.json +0 -0
index df5e07debd2..cacedfb771c 100644

[...]

Quoted 13 lines
qapi/block-core.json +3 -3
@@ -6048,9 +6048,9 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# Notes: In transaction, if @name is empty, or any snapshot matching
-#     @name exists, the operation will fail.  Only some image formats
-#     support it, for example, qcow2, and rbd.
+# .. note:: In transaction, if @name is empty, or any snapshot matching
+#    @name exists, the operation will fail.  Only some image formats
+#    support it, for example, qcow2, and rbd.
 #
 # Since: 1.7
 ##

[...]

author
#37 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 53 lines · Markus Armbruster
Quoted 16 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

Quoted 8 lines

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions

Quoted 26 lines

for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

Quoted 9 lines
Quoted 1 line

This patch uses ".. note::" almost everywhere,

Not mentioned, and may or may not be worth mentioning: both "Note:" and "Notes:" become ".. note::", which renders as "Note". One instance quoted below.

No objection to the change; you obviously double-checked it reads okay that way.

Right, some become "Note" if it feels appropriate, while others (mentioned just below) retained their "Notes" phrasing with a custom admonition if it felt appropriate.

I can mention it more explicitly that some (but not all) "Notes" became "Note".

(I am beginning to have doubts anyone will ever read and find these detailed commits useful, but you're welcome to tell your manager how much you love my commit messages and that I deserve a raise for such heroic efforts. /s)

Quoted 34 lines
Quoted 7 lines

with just two "caution"
directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 4 lines
qapi/block-core.json +0 -0
index df5e07debd2..cacedfb771c 100644

[...]

Quoted 13 lines
qapi/block-core.json +3 -3
@@ -6048,9 +6048,9 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# Notes: In transaction, if @name is empty, or any snapshot matching
-#     @name exists, the operation will fail.  Only some image formats
-#     support it, for example, qcow2, and rbd.
+# .. note:: In transaction, if @name is empty, or any snapshot matching
+#    @name exists, the operation will fail.  Only some image formats
+#    support it, for example, qcow2, and rbd.
 #
 # Since: 1.7
 ##

[...]

#38 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

In reply to John Snow
Quoted 57 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See
https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions
for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 10 lines
qapi/qom.json +0 -2
index 8bd299265e3..5bfa0ded42c 100644
@@ -195,12 +195,12 @@
 #
 # @typename: the type name of an object
 #
-# Note: objects can create properties at runtime, for example to
-#     describe links between different devices and/or objects.  These

qapi/qom.json line 205

Quoted 10 lines
qapi/qom.json +4 -2
-#     properties are not included in the output of this command.
-#
 # Returns: a list of ObjectPropertyInfo describing object properties
 #
+# .. note:: Objects can create properties at runtime, for example to
+#    describe links between different devices and/or objects.  These
+#    properties are not included in the output of this command.
+#
 # Since: 2.12
 ##

You move the note. Commit message doesn't tell why.

Quoted 1 line
qapi/qom.json +0 -0
 { 'command': 'qom-list-properties',

[...]

author
#39 lore raw

Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

Quoted 86 lines · Markus Armbruster
Quoted 16 lines · John Snow

We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.

Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...

... Update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:

Quoted 8 lines

.. note:: lorem ipsum ...

... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol in the title bar for rendered HTML docs.

See

https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions

Quoted 33 lines

for examples of each directive/admonition in use.

These are rendered in orange:

.. Attention:: ...
.. Caution:: ...
.. WARNING:: ...

These are rendered in red:

.. DANGER:: ...
.. Error:: ...

These are rendered in green:

.. Hint:: ...
.. Important:: ...
.. Tip:: ...

These are rendered in blue:

.. Note:: ...
.. admonition:: custom title

admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution" directives. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions.

[...]

Quoted 10 lines
qapi/qom.json +0 -2
index 8bd299265e3..5bfa0ded42c 100644
@@ -195,12 +195,12 @@
 #
 # @typename: the type name of an object
 #
-# Note: objects can create properties at runtime, for example to
-#     describe links between different devices and/or objects.  These

qapi/qom.json line 205

Quoted 10 lines
qapi/qom.json +4 -2
-#     properties are not included in the output of this command.
-#
 # Returns: a list of ObjectPropertyInfo describing object properties
 #
+# .. note:: Objects can create properties at runtime, for example to
+#    describe links between different devices and/or objects.  These
+#    properties are not included in the output of this command.
+#
 # Since: 2.12
 ##

You move the note. Commit message doesn't tell why.

Quoted 4 lines
Quoted 1 line
qapi/qom.json +0 -0
 { 'command': 'qom-list-properties',

[...]

"v2" of this series now declines to move the note in this patch and instead moves it in a separate patch that also enforces source order more strictly so that the move can be explained in detail.

Rendering order diverges from source order briefly as a result; I will mention that in the commit message instead.

(I don't think it's easy or worth doing to re-order the patches such that source and render order never diverge; too much engineering for so temporary a minor issue. Not to mention the source and render order is already divergent in many places, so I don't think it's a regression so much as it is a temporary .... lateralgression?)

author
#40 lore raw

PATCH 10/13 qapi: update prose in note blocks

In reply to John Snow

Where I've noticed, rephrase the note to read more fluently.

---
 qapi/block-core.json | 4 ++--
 qga/qapi-schema.json | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
qapi/block-core.json +2 -2
index cacedfb771c..9ef23ec02ae 100644
@@ -6048,9 +6048,9 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# .. note:: In transaction, if @name is empty, or any snapshot matching
+# .. note:: In a transaction, if @name is empty or any snapshot matching
 #    @name exists, the operation will fail.  Only some image formats
-#    support it, for example, qcow2, and rbd.
+#    support it; for example, qcow2, and rbd.
 #
 # Since: 1.7
 ##
qga/qapi-schema.json +1 -1
index 57598331c5c..1273d85bb5f 100644
@@ -480,7 +480,7 @@
 #
 # Returns: Number of file systems thawed by this call
 #
-# .. note:: If return value does not match the previous call to
+# .. note:: If the return value does not match the previous call to
 #    guest-fsfreeze-freeze, this likely means some freezable filesystems
 #    were unfrozen before this call, and that the filesystem state may
 #    have changed before issuing this command.
Signature · 1 line
2.44.0
Reviewed-by on v1 10/13
#41 lore raw

Re: [PATCH 10/13] qapi: update prose in note blocks

Quoted 29 lines · John Snow

Where I've noticed, rephrase the note to read more fluently.

---
 qapi/block-core.json | 4 ++--
 qga/qapi-schema.json | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
qapi/block-core.json +2 -2
index cacedfb771c..9ef23ec02ae 100644
@@ -6048,9 +6048,9 @@
 #
 # @name: the name of the internal snapshot to be created
 #
-# .. note:: In transaction, if @name is empty, or any snapshot matching
+# .. note:: In a transaction, if @name is empty or any snapshot matching
 #    @name exists, the operation will fail.  Only some image formats
-#    support it, for example, qcow2, and rbd.
+#    support it; for example, qcow2, and rbd.
 #
 # Since: 1.7
 ##
qga/qapi-schema.json +0 -0
index 57598331c5c..1273d85bb5f 100644

qga/qapi-schema.json line 486

Quoted 8 lines
qga/qapi-schema.json +1 -1
@@ -480,7 +480,7 @@
 #
 # Returns: Number of file systems thawed by this call
 #
-# .. note:: If return value does not match the previous call to
+# .. note:: If the return value does not match the previous call to
 #    guest-fsfreeze-freeze, this likely means some freezable filesystems
 #    were unfrozen before this call, and that the filesystem state may
 #    have changed before issuing this command.
author
#42 lore raw

PATCH 11/13 qapi: add markup to note blocks

In reply to John Snow

Generally, surround command-line options with ``literal`` markup to help it stand out from prose in rendered HTML, and add cross-references to replace "see also" messages.

References to types, values, and other QAPI definitions are not yet adjusted here; they will be converted en masse in a subsequent patch after the new QAPI doc generator is merged.

---
 qapi/control.json   | 4 ++--
 qapi/misc.json      | 8 ++++----
 qapi/qdev.json      | 2 +-
 qapi/run-state.json | 2 +-
 qapi/sockets.json   | 2 +-
 qapi/ui.json        | 2 +-
 6 files changed, 10 insertions(+), 10 deletions(-)
qapi/control.json +2 -2
index 59d5e00c151..fe2af45120b 100644
@@ -24,8 +24,8 @@
 #
 # .. note:: This command is valid exactly when first connecting: it must
 #    be issued before any other command will be accepted, and will fail
-#    once the monitor is accepting other commands.  (see qemu
-#    docs/interop/qmp-spec.rst)
+#    once the monitor is accepting other commands.
+#    (see :doc:`/interop/qmp-spec`)
 #
 # .. note:: The QMP client needs to explicitly enable QMP capabilities,
 #    otherwise all the QMP capabilities will be turned off by default.
qapi/misc.json +4 -4
index 13ea82f5254..b04efbadec6 100644
@@ -104,7 +104,7 @@
 # Returns a list of information about each iothread.
 #
 # .. note:: This list excludes the QEMU main loop thread, which is not
-#    declared using the -object iothread command-line option.  It is
+#    declared using the ``-object iothread`` command-line option.  It is
 #    always the main thread of the process.
 #
 # Returns: a list of @IOThreadInfo for each iothread
@@ -138,8 +138,8 @@
 #
 # .. note:: This function will succeed even if the guest is already in
 #    the stopped state.  In "inmigrate" state, it will ensure that the
-#    guest remains paused once migration finishes, as if the -S option
-#    was passed on the command line.
+#    guest remains paused once migration finishes, as if the ``-S``
+#    option was passed on the command line.
 #
 #    In the "suspended" state, it will completely stop the VM and cause
 #    a transition to the "paused" state.  (Since 9.0)
@@ -161,7 +161,7 @@
 # .. note:: This command will succeed if the guest is currently running.
 #    It will also succeed if the guest is in the "inmigrate" state; in
 #    this case, the effect of the command is to make sure the guest
-#    starts once migration finishes, removing the effect of the -S
+#    starts once migration finishes, removing the effect of the ``-S``
 #    command line option if it was passed.
 #
 #    If the VM was previously suspended, and not been reset or woken,
qapi/qdev.json +1 -1
index f5b35a814fe..d031fc3590d 100644
@@ -59,7 +59,7 @@
 #        the 'docs/qdev-device-use.txt' file.
 #
 #     3. It's possible to list device properties by running QEMU with
-#        the "-device DEVICE,help" command-line argument, where DEVICE
+#        the ``-device DEVICE,help`` command-line argument, where DEVICE
 #        is the device's name.
 #
 # Example:
qapi/run-state.json +1 -1
index dc524234ace..252d7d6afa7 100644
@@ -146,7 +146,7 @@
 # @reason: The @ShutdownCause which resulted in the SHUTDOWN.
 #     (since 4.0)
 #
-# .. note:: If the command-line option "-no-shutdown" has been
+# .. note:: If the command-line option ``-no-shutdown`` has been
 #    specified, qemu will not exit, and a STOP event will eventually
 #    follow the SHUTDOWN event.
 #
qapi/sockets.json +1 -1
index 20e05ca7ac2..f46113ab1b8 100644
@@ -181,7 +181,7 @@
 #
 # .. note:: This type is deprecated in favor of SocketAddress.  The
 #    difference between SocketAddressLegacy and SocketAddress is that
-#    the latter has fewer {} on the wire.
+#    the latter has fewer ``{}`` on the wire.
 #
 # Since: 1.3
 ##
qapi/ui.json +1 -1
index a1999965e44..5bcccbfc930 100644
@@ -1268,7 +1268,7 @@
 # Since: 2.6
 #
 # .. note:: The consoles are visible in the qom tree, under
-#    /backend/console[$index]. They have a device link and head
+#    ``/backend/console[$index]``. They have a device link and head
 #    property, so it is possible to map which console belongs to which
 #    device and display.
 #
Signature · 1 line
2.44.0
Reviewed-by on v1 11/13
#43 lore raw

Re: [PATCH 11/13] qapi: add markup to note blocks

Quoted 9 lines · John Snow

Generally, surround command-line options with ``literal`` markup to help it stand out from prose in rendered HTML, and add cross-references to replace "see also" messages.

References to types, values, and other QAPI definitions are not yet adjusted here; they will be converted en masse in a subsequent patch after the new QAPI doc generator is merged.

author
#44 lore raw

PATCH 12/13 qapi/parser: don't parse rST markup as section headers

In reply to John Snow

The double-colon synax is rST formatting that precedes a literal code block. We do not want to capture these as QAPI-specific sections.

Coerce blocks that start with e.g. "Example::" to be parsed as untagged paragraphs instead of special tagged sections.

---
 scripts/qapi/parser.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
scripts/qapi/parser.py +7 -2
index 53b06a94508..971fdf61a09 100644
@@ -545,10 +545,15 @@ def get_doc(self) -> 'QAPIDoc':
                         line = self.get_doc_indented(doc)
                     no_more_args = True
                 elif match := re.match(
-                        r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
-                        line):
+                        r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
+                        r'(?!::): *',
+                        line,
+                ):
                     # tagged section
 
+                    # 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
                     # after we've fully transitioned to the new qapidoc
                     # generator.
Signature · 1 line
2.44.0
#45 lore raw

Re: [PATCH 12/13] qapi/parser: don't parse rST markup as section headers

Quoted 23 lines · John Snow

The double-colon synax is rST formatting that precedes a literal code block. We do not want to capture these as QAPI-specific sections.

Coerce blocks that start with e.g. "Example::" to be parsed as untagged paragraphs instead of special tagged sections.

---
 scripts/qapi/parser.py | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
scripts/qapi/parser.py +2 -2
index 53b06a94508..971fdf61a09 100644
@@ -545,10 +545,15 @@ def get_doc(self) -> 'QAPIDoc':
                         line = self.get_doc_indented(doc)
                     no_more_args = True
                 elif match := re.match(
-                        r'(Returns|Errors|Since|Notes?|Examples?|TODO): *',
-                        line):
+                        r'(Returns|Errors|Since|Notes?|Examples?|TODO)'
+                        r'(?!::): *',

scripts/qapi/parser.py def get_doc(self) -> 'QAPIDoc': · line 559

Quoted 10 lines
scripts/qapi/parser.py +5 -0
+                        line,
+                ):
                     # tagged section
 
+                    # 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
                     # after we've fully transitioned to the new qapidoc
                     # generator.

Patch looks good, but let's add a positive test to doc-good.json.

author
#46 lore raw

PATCH 13/13 qapi: convert "Example" sections to rST

In reply to John Snow

Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done in this patch by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines.

The old "Example:" or "Examples:" syntax is now caught as an error; but with the previous commit, "Example::" is still permitted as explicit rST syntax. ('Example' is not special in this case; any sentence that ends with "::" will start an indented code block in rST.)

The ".. code-block:: QMP" form explicitly applies the QMP lexer and will loosely validate an example as valid QMP/JSON. The "::" form does not apply any lexer in particular and will not emit any errors.

It is possible to choose the QMP lexer with the "::" form by using the Sphinx directive ".. highlight:: QMP" in the document above where the example appears; but this changes the lexer for *all* subsequent "::" style code-blocks in the document thereafter.

This patch does not change the default lexer for the legacy qapidoc generator documents; future patches for the new qapidoc generator *may* change this default.

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 code-block can be captioned independently without bypassing the QMP lexer/validator.

(i.e. code blocks are now for *code* only, so we don't have to sacrifice annotations/captions for having lexicographically correct examples.)

For any sections with more than one example, examples are split up into multiple code-block regions. If annotations are present, those annotations are converted into code-block captions instead, e.g.

```
Examples:

   1. Lorem Ipsum

   -> { "foo": "bar" }
```

Is rewritten as:

```
.. code-block:: QMP
   :caption: Example: Lorem Ipsum

   -> { "foo": "bar" }
```

This process was only semi-automated:

1. Replace "Examples?:" sections with sed:

sed -i 's|# Example:|# .. code-block:: QMP|' *.json sed -i 's|# Examples:|# .. code-block:: QMP|' *.json

2. Identify sections that no longer parse successfully by attempting the doc build, convert annotations into captions manually. (Tedious, oh well.)

3. Add captions where still needed:

sed -zi 's|# .. code-block:: QMP\n#\n|# .. code-block:: QMP\n# :caption: Example\n#\n|g' *.json

Not fully ideal, but hopefully not something that has to be done very often. (Or ever again.)

---
 docs/devel/qapi-code-gen.rst    |  15 ++--
 qapi/acpi.json                  |   6 +-
 qapi/block-core.json            | 120 ++++++++++++++++----------
 qapi/block.json                 |  60 +++++++------
 qapi/char.json                  |  36 ++++++--
 qapi/control.json               |  12 ++-
 qapi/dump.json                  |  12 ++-
 qapi/machine-target.json        |   3 +-
 qapi/machine.json               |  76 +++++++++++------
 qapi/migration.json             | 145 +++++++++++++++++++++++---------
 qapi/misc-target.json           |  33 +++++---
 qapi/misc.json                  |  48 +++++++----
 qapi/net.json                   |  30 +++++--
 qapi/pci.json                   |   6 +-
 qapi/qapi-schema.json           |   6 +-
 qapi/qdev.json                  |  15 +++-
 qapi/qom.json                   |  20 +++--
 qapi/replay.json                |  12 ++-
 qapi/rocker.json                |  12 ++-
 qapi/run-state.json             |  45 ++++++----
 qapi/tpm.json                   |   9 +-
 qapi/trace.json                 |   6 +-
 qapi/transaction.json           |   3 +-
 qapi/ui.json                    |  62 +++++++++-----
 qapi/vfio.json                  |   3 +-
 qapi/virtio.json                |  38 +++++----
 qapi/yank.json                  |   6 +-
 scripts/qapi/parser.py          |  11 ++-
 tests/qapi-schema/doc-good.json |  13 +--
 tests/qapi-schema/doc-good.out  |  18 ++--
 tests/qapi-schema/doc-good.txt  |  17 +---
 31 files changed, 579 insertions(+), 319 deletions(-)
docs/devel/qapi-code-gen.rst +7 -8
index ae97b335cbf..5bf184d16ce 100644
@@ -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,10 +1020,9 @@ 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.
 
 For example::
 
@@ -1058,11 +1057,11 @@ For example::
  #
  # Since: 0.14
  #
- # Example:
+ # .. code-block:: QMP
  #
  #     -> { "execute": "query-blockstats" }
  #     <- {
- #          ... lots of output ...
+ #          ...
  #        }
  ##
  { 'command': 'query-blockstats',
qapi/acpi.json +4 -2
index aa4dbe57943..3da01f1b7fc 100644
@@ -111,7 +111,8 @@
 #
 # Since: 2.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-acpi-ospm-status" }
 #     <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
@@ -131,7 +132,8 @@
 #
 # Since: 2.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "ACPI_DEVICE_OST",
 #          "data": { "info": { "device": "d1", "slot": "0",
qapi/block-core.json +77 -43

348 lines not on this page · raw message

qapi/block.json +34 -26

150 lines not on this page · raw message

qapi/char.json +27 -9
index 5eabf8e7645..1001b902be8 100644
@@ -40,7 +40,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-chardev" }
 #     <- {
@@ -86,7 +87,8 @@
 #
 # Since: 2.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-chardev-backends" }
 #     <- {
@@ -141,7 +143,8 @@
 #
 # Since: 1.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "ringbuf-write",
 #          "arguments": { "device": "foo",
@@ -177,7 +180,8 @@
 #
 # Since: 1.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "ringbuf-read",
 #          "arguments": { "device": "foo",
@@ -699,19 +703,26 @@
 #
 # Since: 1.4
 #
-# Examples:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute" : "chardev-add",
 #          "arguments" : { "id" : "foo",
 #                          "backend" : { "type" : "null", "data" : {} } } }
 #     <- { "return": {} }
 #
+# .. code-block:: QMP
+#    :caption: Example
+#
 #     -> { "execute" : "chardev-add",
 #          "arguments" : { "id" : "bar",
 #                          "backend" : { "type" : "file",
 #                                        "data" : { "out" : "/tmp/bar.log" } } } }
 #     <- { "return": {} }
 #
+# .. code-block:: QMP
+#    :caption: Example
+#
 #     -> { "execute" : "chardev-add",
 #          "arguments" : { "id" : "baz",
 #                          "backend" : { "type" : "pty", "data" : {} } } }
@@ -735,13 +746,17 @@
 #
 # Since: 2.10
 #
-# Examples:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute" : "chardev-change",
 #          "arguments" : { "id" : "baz",
 #                          "backend" : { "type" : "pty", "data" : {} } } }
 #     <- { "return": { "pty" : "/dev/pty/42" } }
 #
+# .. code-block:: QMP
+#    :caption: Example
+#
 #     -> {"execute" : "chardev-change",
 #         "arguments" : {
 #             "id" : "charchannel2",
@@ -772,7 +787,8 @@
 #
 # Since: 1.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
 #     <- { "return": {} }
@@ -789,7 +805,8 @@
 #
 # Since: 2.10
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
 #     <- { "return": {} }
@@ -810,7 +827,8 @@
 #
 # Since: 2.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "VSERPORT_CHANGE",
 #          "data": { "id": "channel0", "open": true },
qapi/control.json +8 -4
index fe2af45120b..938c94eb3ce 100644
@@ -16,7 +16,8 @@
 #     the QMP greeting message.  If the field is not provided, it
 #     means no QMP capabilities will be enabled.  (since 2.12)
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "qmp_capabilities",
 #          "arguments": { "enable": [ "oob" ] } }
@@ -97,7 +98,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-version" }
 #     <- {
@@ -134,7 +136,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-commands" }
 #     <- {
@@ -165,7 +168,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "quit" }
 #     <- { "return": {} }
qapi/dump.json +8 -4
index f9aee7ea1dd..758dc90755a 100644
@@ -94,7 +94,8 @@
 #
 # Since: 1.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "dump-guest-memory",
 #          "arguments": { "paging": false, "protocol": "fd:dump" } }
@@ -150,7 +151,8 @@
 #
 # Since: 2.6
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-dump" }
 #     <- { "return": { "status": "active", "completed": 1024000,
@@ -171,7 +173,8 @@
 #
 # Since: 2.6
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "DUMP_COMPLETED",
 #          "data": { "result": { "total": 1090650112, "status": "completed",
@@ -202,7 +205,8 @@
 #
 # Since: 2.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-dump-guest-memory-capability" }
 #     <- { "return": { "formats":
qapi/machine-target.json +2 -1
index a8d9ec87f59..5d31408abfa 100644
@@ -475,7 +475,8 @@
 #
 # Since: 8.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "CPU_POLARIZATION_CHANGE",
 #          "data": { "polarization": "horizontal" },
qapi/machine.json +48 -28

218 lines not on this page · raw message

qapi/migration.json +103 -42

367 lines not on this page · raw message

qapi/misc-target.json +22 -11
index 2d7d4d89bd5..a60455c367d 100644
@@ -11,7 +11,8 @@
 #
 # Since: 2.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "rtc-reset-reinjection" }
 #     <- { "return": {} }
@@ -133,7 +134,8 @@
 #
 # Since: 2.12
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-sev" }
 #     <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
@@ -164,7 +166,8 @@
 #
 # Since: 2.12
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-sev-launch-measure" }
 #     <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
@@ -209,7 +212,8 @@
 #
 # Since: 2.12
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-sev-capabilities" }
 #     <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
@@ -263,7 +267,8 @@
 #
 # Since: 6.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute" : "query-sev-attestation-report",
 #                      "arguments": { "mnonce": "aaaaaaa" } }
@@ -283,7 +288,8 @@
 #
 # Since: 2.5
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "dump-skeys",
 #          "arguments": { "filename": "/tmp/skeys" } }
@@ -328,7 +334,8 @@
 #
 # Since: 2.6
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-gic-capabilities" }
 #     <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
@@ -386,7 +393,8 @@
 #
 # Since: 6.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-sgx" }
 #     <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
@@ -405,7 +413,8 @@
 #
 # Since: 6.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-sgx-capabilities" }
 #     <- { "return": { "sgx": true, "sgx1" : true, "sgx2" : true,
@@ -480,7 +489,8 @@
 #
 # Since: 8.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "xen-event-list" }
 #     <- { "return": [
@@ -518,7 +528,8 @@
 #
 # Since: 8.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "xen-event-inject", "arguments": { "port": 1 } }
 #     <- { "return": { } }
qapi/misc.json +32 -16

144 lines not on this page · raw message

qapi/net.json +21 -9
index dd6c365c34d..3110d635f46 100644
@@ -26,7 +26,8 @@
 #    command will succeed even if the network adapter does not support
 #    link status notification.
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "set_link",
 #          "arguments": { "name": "e1000.0", "up": false } }
@@ -46,7 +47,8 @@
 # Errors:
 #     - If @type is not a valid network backend, DeviceNotFound
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "netdev_add",
 #          "arguments": { "type": "user", "id": "netdev1",
@@ -68,7 +70,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
 #     <- { "return": {} }
@@ -836,7 +839,8 @@
 #
 # Since: 1.6
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
 #     <- { "return": [
@@ -881,7 +885,8 @@
 #
 # Since: 1.6
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "NIC_RX_FILTER_CHANGED",
 #          "data": { "name": "vnet0",
@@ -930,7 +935,8 @@
 # switches.  This can be useful when network bonds fail-over the
 # active slave.
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "announce-self",
 #          "arguments": {
@@ -955,7 +961,8 @@
 #
 # Since: 4.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "FAILOVER_NEGOTIATED",
 #          "data": { "device-id": "net1" },
@@ -975,7 +982,8 @@
 #
 # Since: 7.2
 #
-# Examples:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "NETDEV_STREAM_CONNECTED",
 #          "data": { "netdev-id": "netdev0",
@@ -983,6 +991,9 @@
 #                              "host": "::1", "type": "inet" } },
 #          "timestamp": { "seconds": 1666269863, "microseconds": 311222 } }
 #
+# .. code-block:: QMP
+#    :caption: Example
+#
 #     <- { "event": "NETDEV_STREAM_CONNECTED",
 #          "data": { "netdev-id": "netdev0",
 #                    "addr": { "path": "/tmp/qemu0", "type": "unix" } },
@@ -1001,7 +1012,8 @@
 #
 # Since: 7.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "NETDEV_STREAM_DISCONNECTED",
 #          "data": {"netdev-id": "netdev0"},
qapi/pci.json +3 -3
index f51159a2c4c..9192212661b 100644
@@ -182,7 +182,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-pci" }
 #     <- { "return": [
@@ -311,8 +312,7 @@
 #           ]
 #        }
 #
-#     Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.
 #
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }
qapi/qapi-schema.json +1 -5
index b1581988e4e..17a5afaacb8 100644
@@ -20,11 +20,7 @@
 # understand.  However, in real protocol usage, they're emitted as a
 # single line.
 #
-# Also, the following notation is used to denote data flow:
-#
-# Example:
-#
-# ::
+# Also, the following notation is used to denote data flow::
 #
 #   -> data issued by the Client
 #   <- Server data response
qapi/qdev.json +11 -4
index d031fc3590d..cfe403fea20 100644
@@ -62,7 +62,8 @@
 #        the ``-device DEVICE,help`` command-line argument, where DEVICE
 #        is the device's name.
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "device_add",
 #          "arguments": { "driver": "e1000", "id": "net1",
@@ -104,12 +105,16 @@
 #
 # Since: 0.14
 #
-# Examples:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "device_del",
 #          "arguments": { "id": "net1" } }
 #     <- { "return": {} }
 #
+# .. code-block:: QMP
+#    :caption: Example
+#
 #     -> { "execute": "device_del",
 #          "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
 #     <- { "return": {} }
@@ -130,7 +135,8 @@
 #
 # Since: 1.5
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "DEVICE_DELETED",
 #          "data": { "device": "virtio-net-pci-0",
@@ -152,7 +158,8 @@
 #
 # Since: 6.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "event": "DEVICE_UNPLUG_GUEST_ERROR",
 #          "data": { "device": "core1",
qapi/qom.json +12 -8
index 5bfa0ded42c..f12a90a2541 100644
@@ -59,7 +59,8 @@
 #
 # Since: 1.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "qom-list",
 #          "arguments": { "path": "/chardevs" } }
@@ -104,16 +105,16 @@
 #
 # Since: 1.2
 #
-# Examples:
-#
-#     1. Use absolute path
+# .. code-block:: QMP
+#    :caption: Example: Use absolute path
 #
 #     -> { "execute": "qom-get",
 #          "arguments": { "path": "/machine/unattached/device[0]",
 #                         "property": "hotplugged" } }
 #     <- { "return": false }
 #
-#     2. Use partial path
+# .. code-block:: QMP
+#    :caption: Example: Use partial path
 #
 #     -> { "execute": "qom-get",
 #          "arguments": { "path": "unattached/sysbus",
@@ -139,7 +140,8 @@
 #
 # Since: 1.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "qom-set",
 #          "arguments": { "path": "/machine",
@@ -1154,7 +1156,8 @@
 #
 # Since: 2.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "object-add",
 #          "arguments": { "qom-type": "rng-random", "id": "rng1",
@@ -1176,7 +1179,8 @@
 #
 # Since: 2.0
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 #     <- { "return": {} }
qapi/replay.json +8 -4
index d3559f9c8f7..f0351b6d9c1 100644
@@ -54,7 +54,8 @@
 #
 # Since: 5.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-replay" }
 #     <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
@@ -76,7 +77,8 @@
 #
 # Since: 5.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "replay-break", "arguments": { "icount": 220414 } }
 #     <- { "return": {} }
@@ -91,7 +93,8 @@
 #
 # Since: 5.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "replay-delete-break" }
 #     <- { "return": {} }
@@ -112,7 +115,8 @@
 #
 # Since: 5.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "replay-seek", "arguments": { "icount": 220414 } }
 #     <- { "return": {} }
qapi/rocker.json +8 -4
index 9f95e638309..da5cc2b9e01 100644
@@ -30,7 +30,8 @@
 #
 # Since: 2.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
 #     <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
@@ -98,7 +99,8 @@
 #
 # Since: 2.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
 #     <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
@@ -240,7 +242,8 @@
 #
 # Since: 2.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-rocker-of-dpa-flows",
 #          "arguments": { "name": "sw1" } }
@@ -315,7 +318,8 @@
 #
 # Since: 2.4
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-rocker-of-dpa-groups",
 #          "arguments": { "name": "sw1" } }
qapi/run-state.json +30 -15

135 lines not on this page · raw message

qapi/tpm.json +6 -3
index 1577b5c259d..07b7b5bd9fd 100644
@@ -31,7 +31,8 @@
 #
 # Since: 1.5
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-tpm-models" }
 #     <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
@@ -62,7 +63,8 @@
 #
 # Since: 1.5
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-tpm-types" }
 #     <- { "return": [ "passthrough", "emulator" ] }
@@ -168,7 +170,8 @@
 #
 # Since: 1.5
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-tpm" }
 #     <- { "return":
qapi/trace.json +4 -2
index 9ebb6d9eaf5..dededbb809e 100644
@@ -51,7 +51,8 @@
 #
 # Since: 2.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "trace-event-get-state",
 #          "arguments": { "name": "qemu_memalign" } }
@@ -74,7 +75,8 @@
 #
 # Since: 2.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "trace-event-set-state",
 #          "arguments": { "name": "qemu_memalign", "enable": true } }
qapi/transaction.json +2 -1
index bcb05fdedd6..3f06ce9c1c6 100644
@@ -244,7 +244,8 @@
 #
 # Since: 1.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "transaction",
 #          "arguments": { "actions": [
qapi/ui.json +40 -22

182 lines not on this page · raw message

qapi/vfio.json +2 -1
index a0e5013188a..2be5b9442b8 100644
@@ -50,7 +50,8 @@
 #
 # Since: 9.1
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     <- { "timestamp": { "seconds": 1713771323, "microseconds": 212268 },
 #          "event": "VFIO_MIGRATION",
qapi/virtio.json +20 -18
index b91f3cdd0df..adf5def9dd6 100644
@@ -34,7 +34,8 @@
 #
 # Since: 7.2
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "x-query-virtio" }
 #     <- { "return": [
@@ -203,9 +204,8 @@
 #
 # Since: 7.2
 #
-# Examples:
-#
-#     1. Poll for the status of virtio-crypto (no vhost-crypto active)
+# .. code-block:: QMP
+#    :caption: Example: 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 +261,8 @@
 #          }
 #        }
 #
-#     2. Poll for the status of virtio-net (vhost-net is active)
+# .. code-block:: QMP
+#    :caption: Example: 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 +569,8 @@
 #
 # Since: 7.2
 #
-# Examples:
-#
-#     1. Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
+# .. code-block:: QMP
+#    :caption: Example: Get VirtQueueStatus for virtio-vsock (vhost-vsock running)
 #
 #     -> { "execute": "x-query-virtio-queue-status",
 #          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
@@ -593,7 +593,8 @@
 #          }
 #        }
 #
-#     2. Get VirtQueueStatus for virtio-serial (no vhost)
+# .. code-block:: QMP
+#    :caption: Example: Get VirtQueueStatus for virtio-serial (no vhost)
 #
 #     -> { "execute": "x-query-virtio-queue-status",
 #          "arguments": { "path": "/machine/peripheral-anon/device[0]/virtio-backend",
@@ -690,9 +691,8 @@
 #
 # Since: 7.2
 #
-# Examples:
-#
-#     1. Get vhost_virtqueue status for vhost-crypto
+# .. code-block:: QMP
+#    :caption: Example: Get vhost_virtqueue status for vhost-crypto
 #
 #     -> { "execute": "x-query-virtio-vhost-queue-status",
 #          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
@@ -715,7 +715,8 @@
 #          }
 #        }
 #
-#     2. Get vhost_virtqueue status for vhost-vsock
+# .. code-block:: QMP
+#    :caption: Example: Get vhost_virtqueue status for vhost-vsock
 #
 #     -> { "execute": "x-query-virtio-vhost-queue-status",
 #          "arguments": { "path": "/machine/peripheral/vsock0/virtio-backend",
@@ -839,9 +840,8 @@
 #
 # Since: 7.2
 #
-# Examples:
-#
-#     1. Introspect on virtio-net's VirtQueue 0 at index 5
+# .. code-block:: QMP
+#    :caption: Example: 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 +870,8 @@
 #          }
 #        }
 #
-#     2. Introspect on virtio-crypto's VirtQueue 1 at head
+# .. code-block:: QMP
+#    :caption: Example: Introspect on virtio-crypto's VirtQueue 1 at head
 #
 #     -> { "execute": "x-query-virtio-queue-element",
 #          "arguments": { "path": "/machine/peripheral/crypto0/virtio-backend",
@@ -898,7 +899,8 @@
 #          }
 #        }
 #
-#     3. Introspect on virtio-scsi's VirtQueue 2 at head
+# .. code-block:: QMP
+#    :caption: Example: Introspect on virtio-scsi's VirtQueue 2 at head
 #
 #     -> { "execute": "x-query-virtio-queue-element",
 #          "arguments": { "path": "/machine/peripheral-anon/device[2]/virtio-backend",
qapi/yank.json +4 -2
index 89f2f4d199b..a64b77e846c 100644
@@ -81,7 +81,8 @@
 # Errors:
 #     - If any of the YankInstances doesn't exist, DeviceNotFound
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "yank",
 #          "arguments": {
@@ -104,7 +105,8 @@
 #
 # Returns: list of @YankInstance
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-yank" }
 #     <- { "return": [
scripts/qapi/parser.py +10 -1
index 971fdf61a09..14de6f460d0 100644
@@ -554,7 +554,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.
 
@@ -568,6 +568,15 @@ 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 rST's "
+                            "'.. code-block:: QMP' directive, 'Example::', "
+                            "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 +8 -5
index 4b338cc0186..2774a7ce14d 100644
@@ -46,11 +46,13 @@
 #
 # Duis aute irure dolor
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example:
 #
 # -> in
 # <- out
-# Examples:
+# .. code-block::
+#
 # - *verbatim*
 # - {braces}
 ##
@@ -172,12 +174,13 @@
 #
 #  Duis aute irure dolor
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #  <- out
 #
-# Examples:
+# .. code-block::
+#
 #  - *verbatim*
 #  - {braces}
 #
@@ -196,7 +199,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #
tests/qapi-schema/doc-good.out +13 -5
index 2c9b4e419cb..347b9cb7134 100644
@@ -93,11 +93,13 @@ Notes:
 
 Duis aute irure dolor
 
-Example:
+.. code-block:: QMP
+   :caption: Example:
 
 -> in
 <- out
-Examples:
+.. code-block::
+
 - *verbatim*
 - {braces}
 doc symbol=Enum
@@ -184,10 +186,14 @@ frobnicate
  - Ut enim ad minim veniam
 
  Duis aute irure dolor
-    section=Example
+
+.. code-block::
+
  -> in
  <- out
-    section=Examples
+
+.. code-block::
+
  - *verbatim*
  - {braces}
     section=Since
@@ -199,7 +205,9 @@ If you're bored enough to read this, go see a video of boxed cats
 a feature
     feature=cmd-feat2
 another feature
-    section=Example
+    section=None
+.. code-block::
+
  -> in
 
  <- out
tests/qapi-schema/doc-good.txt +4 -13
index b89f35d5476..1bd31f0938d 100644
@@ -35,7 +35,10 @@ Duis aute irure dolor
 
 Example:
 
--> in <- out Examples: - *verbatim* - {braces}
+-> in <- out .. code-block:
+
+   - *verbatim*
+   - {braces}
 
 
 "Enum" (Enum)
@@ -219,17 +222,9 @@ Notes:
 
 Duis aute irure dolor
 
-
-Example
-~~~~~~~
-
    -> in
    <- out
 
-
-Examples
-~~~~~~~~
-
    - *verbatim*
    - {braces}
 
@@ -260,10 +255,6 @@ Features
 "cmd-feat2"
    another feature
 
-
-Example
-~~~~~~~
-
    -> in
 
    <- out
Signature · 1 line
2.44.0
#47 lore raw

Re: [PATCH 13/13] qapi: convert "Example" sections to rST

Quoted 23 lines · John Snow

Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done in this patch by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines.

The old "Example:" or "Examples:" syntax is now caught as an error; but with the previous commit, "Example::" is still permitted as explicit rST syntax. ('Example' is not special in this case; any sentence that ends with "::" will start an indented code block in rST.)

The ".. code-block:: QMP" form explicitly applies the QMP lexer and will loosely validate an example as valid QMP/JSON. The "::" form does not apply any lexer in particular and will not emit any errors.

It is possible to choose the QMP lexer with the "::" form by using the Sphinx directive ".. highlight:: QMP" in the document above where the example appears; but this changes the lexer for *all* subsequent "::" style code-blocks in the document thereafter.

This patch does not change the default lexer for the legacy qapidoc generator documents; future patches for the new qapidoc generator *may* change this default.

Quoted 6 lines

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.

Do the double-quotes signify something I'm missing?

Quoted 56 lines

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 code-block can be captioned independently without bypassing the QMP lexer/validator.

(i.e. code blocks are now for *code* only, so we don't have to sacrifice annotations/captions for having lexicographically correct examples.)

For any sections with more than one example, examples are split up into multiple code-block regions. If annotations are present, those annotations are converted into code-block captions instead, e.g.

```
Examples:

   1. Lorem Ipsum

   -> { "foo": "bar" }
```

Is rewritten as:

```
.. code-block:: QMP
   :caption: Example: Lorem Ipsum

   -> { "foo": "bar" }
```

This process was only semi-automated:

1. Replace "Examples?:" sections with sed:

sed -i 's|# Example:|# .. code-block:: QMP|' *.json sed -i 's|# Examples:|# .. code-block:: QMP|' *.json

2. Identify sections that no longer parse successfully by attempting the doc build, convert annotations into captions manually. (Tedious, oh well.)

3. Add captions where still needed:

sed -zi 's|# .. code-block:: QMP\n#\n|# .. code-block:: QMP\n# :caption: Example\n#\n|g' *.json

Not fully ideal, but hopefully not something that has to be done very often. (Or ever again.)

[...]

Quoted 15 lines
qapi/pci.json +2 -1
index f51159a2c4c..9192212661b 100644
@@ -182,7 +182,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-pci" }
 #     <- { "return": [

qapi/pci.json line 315

Quoted 6 lines
qapi/pci.json +1 -2
@@ -311,8 +312,7 @@
 #           ]
 #        }
 #
-#     Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.

Squash into PATCH 09.

qapi/pci.json line 318

Quoted 3 lines
qapi/pci.json +0 -0
 #
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }

Otherwise looks good to me except for the somewhat ugly rendering in HTML mentioned in the commit message.

[...]

author
#48 lore raw

Re: [PATCH 13/13] qapi: convert "Example" sections to rST

Quoted 25 lines · Markus Armbruster
Quoted 23 lines · John Snow

Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done in this patch by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines.

The old "Example:" or "Examples:" syntax is now caught as an error; but with the previous commit, "Example::" is still permitted as explicit rST syntax. ('Example' is not special in this case; any sentence that ends with "::" will start an indented code block in rST.)

The ".. code-block:: QMP" form explicitly applies the QMP lexer and will loosely validate an example as valid QMP/JSON. The "::" form does not apply any lexer in particular and will not emit any errors.

It is possible to choose the QMP lexer with the "::" form by using the Sphinx directive ".. highlight:: QMP" in the document above where the example appears; but this changes the lexer for *all* subsequent "::" style code-blocks in the document thereafter.

This patch does not change the default lexer for the legacy qapidoc generator documents; future patches for the new qapidoc generator *may* change this default.

Quoted 9 lines
Quoted 6 lines

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.

Do the double-quotes signify something I'm missing?

They aren't *sections* (QAPIDoc terminology) anymore, but was at a loss for more precise phrasing.

Quoted 84 lines
Quoted 43 lines

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 code-block can be captioned independently without bypassing the QMP lexer/validator.

(i.e. code blocks are now for *code* only, so we don't have to sacrifice annotations/captions for having lexicographically correct examples.)

For any sections with more than one example, examples are split up into multiple code-block regions. If annotations are present, those annotations are converted into code-block captions instead, e.g.

```
Examples:

   1. Lorem Ipsum

   -> { "foo": "bar" }
```

Is rewritten as:

```
.. code-block:: QMP
   :caption: Example: Lorem Ipsum

   -> { "foo": "bar" }
```

This process was only semi-automated:

1. Replace "Examples?:" sections with sed:

sed -i 's|# Example:|# .. code-block:: QMP|' *.json sed -i 's|# Examples:|# .. code-block:: QMP|' *.json

Quoted 7 lines

2. Identify sections that no longer parse successfully by attempting the doc build, convert annotations into captions manually. (Tedious, oh well.)

3. Add captions where still needed:

sed -zi 's|# .. code-block:: QMP\n#\n|# .. code-block:: QMP\n#

:caption: Example\n#\n|g' *.json

Quoted 6 lines

Not fully ideal, but hopefully not something that has to be done very often. (Or ever again.)

[...]

Quoted 15 lines
qapi/pci.json +2 -1
index f51159a2c4c..9192212661b 100644
@@ -182,7 +182,8 @@
 #
 # Since: 0.14
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example
 #
 #     -> { "execute": "query-pci" }
 #     <- { "return": [

qapi/pci.json line 315

Quoted 6 lines
qapi/pci.json +1 -2
@@ -311,8 +312,7 @@
 #           ]
 #        }
 #
-#     Note: This example has been shortened as the real response is too
-#     long.
+# This example has been shortened as the real response is too long.

Squash into PATCH 09.

Quoted 7 lines

qapi/pci.json line 318

Quoted 3 lines
qapi/pci.json +0 -0
 #
 ##
 { 'command': 'query-pci', 'returns': ['PciInfo'] }

Otherwise looks good to me except for the somewhat ugly rendering in HTML mentioned in the commit message.

ACK

Quoted 3 lines

[...]

#49 lore raw

Re: [PATCH 13/13] qapi: convert "Example" sections to rST

In reply to John Snow
Quoted 4 lines · John Snow

Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done in this patch by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines.

[...]

Quoted 4 lines
qapi/migration.json +0 -0
index 85a14bb4308..849358b6387 100644

[...]

Quoted 27 lines
qapi/migration.json +22 -1
@@ -336,7 +338,35 @@
 #           }
 #        }
 #
-#     5. Migration is being performed and XBZRLE is active:
+# .. code-block:: QMP
+#    :caption: Example: Migration is being performed and XBZRLE is active
+#
+#     -> { "execute": "query-migrate" }
+#     <- {
+#           "return":{
+#              "status":"active",
+#              "total-time":12345,
+#              "setup-time":12345,
+#              "expected-downtime":12345,
+#              "ram":{
+#                 "total":1057024,
+#                 "remaining":1053304,
+#                 "transferred":3720,
+#                 "duplicate":123,
+#                 "normal":123,
+#                 "normal-bytes":123456,
+#                 "dirty-sync-count":15
+#              },
+#              "disk":{
+#                 "total":20971520,
+#                 "remaining":20880384,

qapi/migration.json line 372

Quoted 10 lines
qapi/migration.json +7 -0
+#                 "transferred":91136
+#              }
+#           }
+#        }
+#
+# .. code-block:: QMP
+#    :caption: Example: Migration is being performed and XBZRLE is active
 #
 #     -> { "execute": "query-migrate" }
 #     <- {

Example accidentally duplicated.

[...]

tests/qapi-schema/doc-good.json line 50

Quoted 11 lines
tests/qapi-schema/doc-good.json +2 -1
index 4b338cc0186..2774a7ce14d 100644
@@ -46,11 +46,13 @@
 #
 # Duis aute irure dolor
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example:

See [*] below.

tests/qapi-schema/doc-good.json line 55

Quoted 6 lines
tests/qapi-schema/doc-good.json +2 -1
 #
 # -> in
 # <- out
-# Examples:
+# .. code-block::
+#

Likewise.

Quoted 33 lines
tests/qapi-schema/doc-good.json +4 -3
 # - *verbatim*
 # - {braces}
 ##
@@ -172,12 +174,13 @@
 #
 #  Duis aute irure dolor
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #  <- out
 #
-# Examples:
+# .. code-block::
+#
 #  - *verbatim*
 #  - {braces}
 #
@@ -196,7 +199,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #
tests/qapi-schema/doc-good.out +0 -0
index 2c9b4e419cb..347b9cb7134 100644

tests/qapi-schema/doc-good.out Notes: · line 97

Quoted 6 lines
tests/qapi-schema/doc-good.out +2 -1
@@ -93,11 +93,13 @@ Notes:
 
 Duis aute irure dolor
 
-Example:
+.. code-block:: QMP
+   :caption: Example:

[*] This demonstrates the "Example: ..." is *not* recognized as a "Example" section before the patch (compare to the change we get for recognized sections below).

I pointed out the same issue for "Note" in review of PATCH 9, and suggested ways to resolve it. Pick a way there, and use it here as well

Quoted 42 lines
tests/qapi-schema/doc-good.out +11 -4
 -> in
 <- out
-Examples:
+.. code-block::
+
 - *verbatim*
 - {braces}
 doc symbol=Enum
@@ -184,10 +186,14 @@ frobnicate
  - Ut enim ad minim veniam
 
  Duis aute irure dolor
-    section=Example
+
+.. code-block::
+
  -> in
  <- out
-    section=Examples
+
+.. code-block::
+
  - *verbatim*
  - {braces}
     section=Since
@@ -199,7 +205,9 @@ If you're bored enough to read this, go see a video of boxed cats
 a feature
     feature=cmd-feat2
 another feature
-    section=Example
+    section=None
+.. code-block::
+
  -> in
 
  <- out
tests/qapi-schema/doc-good.txt +0 -0
index b89f35d5476..1bd31f0938d 100644

tests/qapi-schema/doc-good.txt Duis aute irure dolor · line 38

Quoted 5 lines
tests/qapi-schema/doc-good.txt +1 -1
@@ -35,7 +35,10 @@ Duis aute irure dolor
 
 Example:
 
--> in <- out Examples: - *verbatim* - {braces}
+-> in <- out .. code-block:

Looks like Sphinx didn't recognize the .. code-block: directive. Generator bug?

Quoted 25 lines
tests/qapi-schema/doc-good.txt +3 -8
+
+   - *verbatim*
+   - {braces}
 
 
 "Enum" (Enum)
@@ -219,17 +222,9 @@ Notes:
 
 Duis aute irure dolor
 
-
-Example
-~~~~~~~
-
    -> in
    <- out
 
-
-Examples
-~~~~~~~~
-
    - *verbatim*
    - {braces}
 

tests/qapi-schema/doc-good.txt Features · line 260

Quoted 10 lines
tests/qapi-schema/doc-good.txt +0 -4
@@ -260,10 +255,6 @@ Features
 "cmd-feat2"
    another feature
 
-
-Example
-~~~~~~~
-
    -> in
 
    <- out

Rendering to text now loses the "Example" heading.

We render to manual pages in addition to HTML. Looks like we don't lose "Example" there. Odd.

We render to text only for diffing purposes. The loss there could perhaps be tolerated. Still, could you avoid it with reasonable effort?

author
#50 lore raw

Re: [PATCH 13/13] qapi: convert "Example" sections to rST

Quoted 52 lines · Markus Armbruster
Quoted 4 lines · John Snow

Eliminate the "Example" sections in QAPI doc blocks, converting them into QMP example code blocks. This is generally done in this patch by converting "Example:" or "Examples:" lines into ".. code-block:: QMP" lines.

[...]

Quoted 4 lines
qapi/migration.json +0 -0
index 85a14bb4308..849358b6387 100644

[...]

qapi/migration.json line 342

Quoted 7 lines
qapi/migration.json +2 -1
@@ -336,7 +338,35 @@
 #           }
 #        }
 #
-#     5. Migration is being performed and XBZRLE is active:
+# .. code-block:: QMP
+#    :caption: Example: Migration is being performed and XBZRLE is

active

Quoted 17 lines
qapi/migration.json +17 -0
+#
+#     -> { "execute": "query-migrate" }
+#     <- {
+#           "return":{
+#              "status":"active",
+#              "total-time":12345,
+#              "setup-time":12345,
+#              "expected-downtime":12345,
+#              "ram":{
+#                 "total":1057024,
+#                 "remaining":1053304,
+#                 "transferred":3720,
+#                 "duplicate":123,
+#                 "normal":123,
+#                 "normal-bytes":123456,
+#                 "dirty-sync-count":15
+#              },

qapi/migration.json

Quoted 10 lines
qapi/migration.json +10 -0
+#              "disk":{
+#                 "total":20971520,
+#                 "remaining":20880384,
+#                 "transferred":91136
+#              }
+#           }
+#        }
+#
+# .. code-block:: QMP
+#    :caption: Example: Migration is being performed and XBZRLE is

active

Quoted 6 lines

qapi/migration.json line 323

Quoted 3 lines
qapi/migration.json +0 -0
 #
 #     -> { "execute": "query-migrate" }
 #     <- {

Example accidentally duplicated.

Fixed this yesterday, oopsie. I think this was a rebase goof.

Quoted 72 lines

[...]

Review

Quoted 1 line
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.json

tests/qapi-schema/doc-good.json line 50

Quoted 10 lines

index 4b338cc0186..2774a7ce14d 100644

tests/qapi-schema/doc-good.json +2 -1
@@ -46,11 +46,13 @@
 #
 # Duis aute irure dolor
 #
-# Example:
+# .. code-block:: QMP
+#    :caption: Example:

See [*] below.

tests/qapi-schema/doc-good.json line 55

Quoted 6 lines
tests/qapi-schema/doc-good.json +2 -1
 #
 # -> in
 # <- out
-# Examples:
+# .. code-block::
+#

Likewise.

Review

Quoted 29 lines
tests/qapi-schema/doc-good.json +4 -3
 # - *verbatim*
 # - {braces}
 ##
@@ -172,12 +174,13 @@
 #
 #  Duis aute irure dolor
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #  <- out
 #
-# Examples:
+# .. code-block::
+#
 #  - *verbatim*
 #  - {braces}
 #
@@ -196,7 +199,7 @@
 # @cmd-feat1: a feature
 # @cmd-feat2: another feature
 #
-# Example:
+# .. code-block::
 #
 #  -> in
 #
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.out

tests/qapi-schema/doc-good.out Notes: · line 97

Quoted 10 lines

index 2c9b4e419cb..347b9cb7134 100644

tests/qapi-schema/doc-good.out +2 -1
@@ -93,11 +93,13 @@ Notes:
 
 Duis aute irure dolor
 
-Example:
+.. code-block:: QMP
+   :caption: Example:

[*] This demonstrates the "Example: ..." is *not* recognized as a "Example" section before the patch (compare to the change we get for recognized sections below).

Quoted 3 lines

I pointed out the same issue for "Note" in review of PATCH 9, and suggested ways to resolve it. Pick a way there, and use it here as well

ACK

Quoted 45 lines

tests/qapi-schema/doc-good.out If you're bored enough to read this, go see a video

Quoted 27 lines
tests/qapi-schema/doc-good.out +8 -3
 -> in
 <- out
-Examples:
+.. code-block::
+
 - *verbatim*
 - {braces}
 doc symbol=Enum
@@ -184,10 +186,14 @@ frobnicate
  - Ut enim ad minim veniam
 
  Duis aute irure dolor
-    section=Example
+
+.. code-block::
+
  -> in
  <- out
-    section=Examples
+
+.. code-block::
+
  - *verbatim*
  - {braces}
     section=Since
@@ -199,7 +205,9 @@ If you're bored enough to read this, go see a video

of boxed cats

Review

Quoted 11 lines
tests/qapi-schema/doc-good.out +3 -1
 a feature
     feature=cmd-feat2
 another feature
-    section=Example
+    section=None
+.. code-block::
+
  -> in
 
  <- out
(quoted diff) +0 -0

b/tests/qapi-schema/doc-good.txt

Quoted 5 lines

index b89f35d5476..1bd31f0938d 100644

tests/qapi-schema/doc-good.txt +0 -0
@@ -35,7 +35,10 @@ Duis aute irure dolor
 
Quoted 8 lines

tests/qapi-schema/doc-good.txt Duis aute irure dolor · line 38

Quoted 4 lines
tests/qapi-schema/doc-good.txt +1 -1
 Example:
 
--> in <- out Examples: - *verbatim* - {braces}
+-> in <- out .. code-block:

Looks like Sphinx didn't recognize the .. code-block: directive. Generator bug?

Honestly, not sure. Depends on what generates the plaintext...

... on IRC just now you say it's a Sphinx builder. I'll investigate why this happens before resending.

Quoted 38 lines
Quoted 25 lines
tests/qapi-schema/doc-good.txt +3 -8
+
+   - *verbatim*
+   - {braces}
 
 
 "Enum" (Enum)
@@ -219,17 +222,9 @@ Notes:
 
 Duis aute irure dolor
 
-
-Example
-~~~~~~~
-
    -> in
    <- out
 
-
-Examples
-~~~~~~~~
-
    - *verbatim*
    - {braces}
 

tests/qapi-schema/doc-good.txt Features · line 260

Quoted 10 lines
tests/qapi-schema/doc-good.txt +0 -4
@@ -260,10 +255,6 @@ Features
 "cmd-feat2"
    another feature
 
-
-Example
-~~~~~~~
-
    -> in
 
    <- out

Rendering to text now loses the "Example" heading.

Quoted 6 lines

We render to manual pages in addition to HTML. Looks like we don't lose "Example" there. Odd.

We render to text only for diffing purposes. The loss there could perhaps be tolerated. Still, could you avoid it with reasonable effort?

I've rewritten how Examples are handled; I'll check to see how they render to plaintext and see what can be done.

Quoted 1 line
#51 lore raw
In reply to John Snow

You asked for a summary of my review findings. Here it is:

* PATCH 01: DO-NOT-MERGE, not reviewed

* PATCH 02, 05..07, 10..12: R-by or A-by

* PATCH 03: R-by with straightforward minor adjustments

* PATCH 04, 08: R-by with commit message and doc tweaks

* PATCH 09:

- Commit message tweaks

- You convert "Note:" even in free-form doc, where it isn't recognized; separate patch or mention in commit message

- You silently move one note; don't, separate patch, or mention in commit message

- Tweak doc-interleaved-section.json

- A few more notes need to start with a capital letter and / or end with a period

- I don't like the indentation change

* PATCH 12: Want a positive test

* PATCH 13:

- One hunk should be squashed into PATCH 09

- Accidentally duplicated example should be dropped

- You convert "Example:" even in free-form doc, where it isn't recognized; separate patch or mention in commit message

- Sphinx doesn't recognize a .. code-block: directive in doc-good.json

- doc-good.txt loses "Example"

- Generated HTML looks somehwat ugly

Feel free to leave reverting indentation changes to me. Same for starting notes with a capital letter and ending them with a period.

I'm willing to accept ugly HTML along with a promise of future improvement :)

Reviewed-by on the v1 series
#52 lore raw
In reply to John Snow
Quoted 22 lines · John Snow

This series focuses primarily on converting our existing QAPI/QMP documentation to remove special "Note" and "Example" sections in favor of rST markup for the same.

This is being done primarily to reduce the number of specially parsed QAPI sections we have in favor of allowing fully arbitrary rST markup for greater flexibility and freedom in styling the rendered HTML documentation.

(A tangible side benefit is that the new qapidoc generator has fewer sections to reason about when it splices inherited documentation together for the QMP reference manual; docs largely preserve the order of documentation "as written" instead of needing to splice multiple separate sections together. A goal of the new generator is to eventually remove all tagged sections except for "members" and "features".)

Known issues:

- The caption syntax for QMP examples is a little ugly in rendered HTML output; My CSS intern wasn't available before publication time to fix it ;) -- Will fix with an amendment patch at next opportunity.

Quoted 5 lines

Any feedback not implemented should be interpreted as evidence of a forgetful (rather than a spiteful) mind. Please remind me where appropriate.

--js

virtio things:

Quoted 66 lines

John Snow (13):
[DO-NOT-MERGE]: Add some ad-hoc linting helpers.
qapi: linter fixups
docs/qapidoc: delint a tiny portion of the module qapi/parser: preserve indentation in QAPIDoc sections qapi/parser: fix comment parsing immediately following a doc block docs/qapidoc: fix nested parsing under untagged sections
qapi: fix non-compliant JSON examples
qapi: ensure all errors sections are uniformly typset
qapi: convert "Note" sections to plain rST
qapi: update prose in note blocks
qapi: add markup to note blocks
qapi/parser: don't parse rST markup as section headers
qapi: convert "Example" sections to rST

 docs/devel/qapi-code-gen.rst                  |  25 +--
 docs/sphinx/qapidoc.py                        | 103 ++++++++----
 qapi/acpi.json                                |   6 +-
 qapi/block-core.json                          | 148 +++++++++-------
 qapi/block.json                               |  62 ++++---
 qapi/char.json                                |  48 ++++--
 qapi/control.json                             |  32 ++--
 qapi/dump.json                                |  14 +-
 qapi/introspect.json                          |   6 +-
 qapi/machine-target.json                      |  29 ++--
 qapi/machine.json                             | 125 ++++++++------
 qapi/migration.json                           | 159 ++++++++++++------
 qapi/misc-target.json                         |  33 ++--
 qapi/misc.json                                | 139 ++++++++-------
 qapi/net.json                                 |  42 +++--
 qapi/pci.json                                 |  11 +-
 qapi/qapi-schema.json                         |   6 +-
 qapi/qdev.json                                |  45 ++---
 qapi/qom.json                                 |  39 +++--
 qapi/replay.json                              |  12 +-
 qapi/rocker.json                              |  30 ++--
 qapi/run-state.json                           |  63 ++++---
 qapi/sockets.json                             |  10 +-
 qapi/stats.json                               |  22 +--
 qapi/tpm.json                                 |   9 +-
 qapi/trace.json                               |   6 +-
 qapi/transaction.json                         |  13 +-
 qapi/ui.json                                  |  93 +++++-----
 qapi/vfio.json                                |   3 +-
 qapi/virtio.json                              |  50 +++---
 qapi/yank.json                                |   6 +-
 qga/qapi-schema.json                          |  48 +++---
 scripts/qapi-lint.sh                          |  59 +++++++
 scripts/qapi/Makefile                         |   5 +
 scripts/qapi/introspect.py                    |   8 +-
 scripts/qapi/parser.py                        |  40 ++++-
 scripts/qapi/schema.py                        |   6 +-
 scripts/qapi/visit.py                         |   5 +-
 tests/qapi-schema/doc-empty-section.err       |   2 +-
 tests/qapi-schema/doc-empty-section.json      |   2 +-
 tests/qapi-schema/doc-good.json               |  21 ++-
 tests/qapi-schema/doc-good.out                |  62 ++++---
 tests/qapi-schema/doc-good.txt                |  31 ++--
 .../qapi-schema/doc-interleaved-section.json  |   2 +-
 44 files changed, 1036 insertions(+), 644 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile
Signature · 1 line
2.44.0