* [PULL 00/13] QAPI patches patches for 2024-07-06
@ 2024-07-06 7:24 Markus Armbruster
2024-07-06 7:24 ` [PULL 01/13] qapi: linter fixups Markus Armbruster
` (13 more replies)
0 siblings, 14 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson
The following changes since commit f2cb4026fccfe073f84a4b440e41d3ed0c3134f6:
Merge tag 'pull-maintainer-july24-050724-1' of https://gitlab.com/stsquad/qemu into staging (2024-07-05 09:15:48 -0700)
are available in the Git repository at:
https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-07-06
for you to fetch changes up to e389929d19a543ea5b34d02553b355f9f1c03162:
sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments (2024-07-06 08:58:24 +0200)
----------------------------------------------------------------
QAPI patches patches for 2024-07-06
----------------------------------------------------------------
John Snow (12):
qapi: linter fixups
docs/qapidoc: remove unused intersperse function
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: nail down convention that Errors sections are lists
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
Markus Armbruster (1):
sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
docs/devel/qapi-code-gen.rst | 14 ++-
docs/sphinx/qapidoc.py | 115 +++++++++++++++----------
qapi/block-core.json | 35 +++-----
qapi/block.json | 2 +-
qapi/char.json | 12 +--
qapi/control.json | 20 ++---
qapi/dump.json | 2 +-
qapi/introspect.json | 6 +-
qapi/machine-target.json | 26 +++---
qapi/machine.json | 49 +++++------
qapi/migration.json | 16 ++--
qapi/misc.json | 91 ++++++++++---------
qapi/net.json | 12 +--
qapi/pci.json | 8 +-
qapi/qdev.json | 30 +++----
qapi/qom.json | 17 ++--
qapi/rocker.json | 18 ++--
qapi/run-state.json | 18 ++--
qapi/sockets.json | 10 +--
qapi/stats.json | 22 ++---
qapi/transaction.json | 10 +--
qapi/ui.json | 31 ++++---
qapi/virtio.json | 12 +--
qga/qapi-schema.json | 48 +++++------
scripts/qapi/introspect.py | 8 +-
scripts/qapi/parser.py | 30 +++++--
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 | 9 +-
tests/qapi-schema/doc-good.out | 43 +++++----
tests/qapi-schema/doc-good.txt | 13 ++-
tests/qapi-schema/doc-interleaved-section.json | 2 +-
34 files changed, 397 insertions(+), 347 deletions(-)
--
2.45.0
^ permalink raw reply [flat|nested] 15+ messages in thread
* [PULL 01/13] qapi: linter fixups
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 02/13] docs/qapidoc: remove unused intersperse function Markus Armbruster
` (12 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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.)
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-3-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/introspect.py | 8 ++++----
scripts/qapi/schema.py | 6 +++---
scripts/qapi/visit.py | 5 +++--
3 files changed, 10 insertions(+), 9 deletions(-)
diff --git a/scripts/qapi/introspect.py b/scripts/qapi/introspect.py
index 86c075a6ad..ac14b20f30 100644
--- a/scripts/qapi/introspect.py
+++ b/scripts/qapi/introspect.py
@@ -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)
diff --git a/scripts/qapi/schema.py b/scripts/qapi/schema.py
index 721c470d2b..d65c35f6ee 100644
--- a/scripts/qapi/schema.py
+++ b/scripts/qapi/schema.py
@@ -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))
diff --git a/scripts/qapi/visit.py b/scripts/qapi/visit.py
index e766acaac9..12f92e429f 100644
--- a/scripts/qapi/visit.py
+++ b/scripts/qapi/visit.py
@@ -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;
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 02/13] docs/qapidoc: remove unused intersperse function
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
2024-07-06 7:24 ` [PULL 01/13] qapi: linter fixups Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 03/13] docs/qapidoc: delint a tiny portion of the module Markus Armbruster
` (11 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
This function has been unused since since commit
fd62bff901b (sphinx/qapidoc: Drop code to generate doc for simple
union tag).
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240626222128.406106-4-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 10 ----------
1 file changed, 10 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index f270b494f0..3c0565d0ce 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -50,16 +50,6 @@
__version__ = '1.0'
-# 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)
- for item in iterable:
- yield separator
- yield item
-
-
class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
"""A QAPI schema visitor which generates docutils/Sphinx nodes
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 03/13] docs/qapidoc: delint a tiny portion of the module
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
2024-07-06 7:24 ` [PULL 01/13] qapi: linter fixups Markus Armbruster
2024-07-06 7:24 ` [PULL 02/13] docs/qapidoc: remove unused intersperse function Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 04/13] qapi/parser: preserve indentation in QAPIDoc sections Markus Armbruster
` (10 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-5-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 62 +++++++++++++++++++++++++-----------------
1 file changed, 37 insertions(+), 25 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 3c0565d0ce..659e507353 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -28,26 +28,33 @@
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 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
-import sphinx
-from qapi.gen import QAPISchemaVisitor
-from qapi.error import QAPIError, QAPISemError
-from qapi.schema import QAPISchema
# 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
class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
@@ -441,6 +448,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
@@ -448,34 +459,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:
@@ -513,13 +524,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:
@@ -527,12 +539,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,
+ }
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 04/13] qapi/parser: preserve indentation in QAPIDoc sections
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (2 preceding siblings ...)
2024-07-06 7:24 ` [PULL 03/13] docs/qapidoc: delint a tiny portion of the module Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 05/13] qapi/parser: fix comment parsing immediately following a doc block Markus Armbruster
` (9 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
Change get_doc_indented() to preserve indentation on all subsequent text
lines, and create a compatibility dedent() function for qapidoc.py that
removes indentation the same way get_doc_indented() did.
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 into:
```
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 into:
```
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.
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.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-6-jsnow@redhat.com>
[Lost commit message paragraph restored]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 27 ++++++++++++++++++++++-----
scripts/qapi/parser.py | 4 ++--
tests/qapi-schema/doc-good.out | 32 ++++++++++++++++----------------
3 files changed, 40 insertions(+), 23 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index 659e507353..f9683444b1 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -26,6 +26,7 @@
import os
import re
+import textwrap
from docutils import nodes
from docutils.parsers.rst import Directive, directives
@@ -53,6 +54,19 @@
__version__ = "1.0"
+def dedent(text: str) -> str:
+ # Adjust indentation to make description text parse as paragraph.
+
+ 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
@@ -164,7 +178,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')]
@@ -202,7 +216,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')]
@@ -237,7 +251,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:
@@ -260,9 +274,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
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 7b13a583ac..1ef1f85b02 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -448,7 +448,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 +465,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]:
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 716a9a4102..435f6e6d76 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -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=
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 05/13] qapi/parser: fix comment parsing immediately following a doc block
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (3 preceding siblings ...)
2024-07-06 7:24 ` [PULL 04/13] qapi/parser: preserve indentation in QAPIDoc sections Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 06/13] docs/qapidoc: fix nested parsing under untagged sections Markus Armbruster
` (8 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
If a comment immediately follows a doc block, the parser doesn't ignore
that token appropriately. Fix that.
e.g.
> ##
> # = 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)
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-7-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/parser.py | 2 +-
tests/qapi-schema/doc-good.json | 2 ++
2 files changed, 3 insertions(+), 1 deletion(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 1ef1f85b02..c3d20cc01b 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -583,7 +583,7 @@ def get_doc(self) -> 'QAPIDoc':
line = self.get_doc_line()
first = False
- self.accept(False)
+ self.accept()
doc.end()
return doc
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index de38a386e8..8b39eb946a 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -55,6 +55,8 @@
# - {braces}
##
+# Not a doc comment
+
##
# @Enum:
#
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 06/13] docs/qapidoc: fix nested parsing under untagged sections
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (4 preceding siblings ...)
2024-07-06 7:24 ` [PULL 05/13] qapi/parser: fix comment parsing immediately following a doc block Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 07/13] qapi: fix non-compliant JSON examples Markus Armbruster
` (7 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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.
The resulting output changes are basically invisible.
Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-8-jsnow@redhat.com>
[Mention output changes in commit message]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/sphinx/qapidoc.py | 16 +++++++++++-----
1 file changed, 11 insertions(+), 5 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index f9683444b1..efcd84656f 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -272,14 +272,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
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 07/13] qapi: fix non-compliant JSON examples
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (5 preceding siblings ...)
2024-07-06 7:24 ` [PULL 06/13] docs/qapidoc: fix nested parsing under untagged sections Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 08/13] qapi: nail down convention that Errors sections are lists Markus Armbruster
` (6 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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). Additionally, elisions must be standardized for the QMP lexer;
they must be represented as the value "...", so three examples have been
adjusted to support that format here.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-9-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
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(-)
diff --git a/qapi/control.json b/qapi/control.json
index 6bdbf077c2..10c906fa0e 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -145,7 +145,8 @@
# },
# {
# "name":"system_powerdown"
-# }
+# },
+# ...
# ]
# }
#
diff --git a/qapi/machine.json b/qapi/machine.json
index 2fd3e9c3d5..a982c94503 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -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:
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 0f24206bce..9ec9ef36c4 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -2106,7 +2106,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:
diff --git a/qapi/misc.json b/qapi/misc.json
index ec30e5c570..4b41e15dcd 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -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' }
diff --git a/qapi/net.json b/qapi/net.json
index 0f5a259475..c19df435a5 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -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' } }
diff --git a/qapi/rocker.json b/qapi/rocker.json
index 5635cf174f..f5225eb62c 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -250,7 +250,7 @@
# "action": {"goto-tbl": 10},
# "mask": {"in-pport": 4294901760}
# },
-# {...more...},
+# {...},
# ]}
##
{ 'command': 'query-rocker-of-dpa-flows',
diff --git a/qapi/ui.json b/qapi/ui.json
index f610bce118..c12f529257 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -361,7 +361,7 @@
# "channel-id": 0,
# "tls": false
# },
-# [ ... more channels follow ... ]
+# ...
# ]
# }
# }
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 08/13] qapi: nail down convention that Errors sections are lists
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (6 preceding siblings ...)
2024-07-06 7:24 ` [PULL 07/13] qapi: fix non-compliant JSON examples Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 09/13] qapi: convert "Note" sections to plain rST Markus Armbruster
` (5 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
By unstated convention, Errors sections are rST lists. Document the
convention, and make the one exception conform.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-10-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
docs/devel/qapi-code-gen.rst | 7 +++++++
qapi/transaction.json | 2 +-
2 files changed, 8 insertions(+), 1 deletion(-)
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index f453bd3546..cee43222f1 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -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.
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 5749c133d4..07afc269d5 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -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
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 09/13] qapi: convert "Note" sections to plain rST
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (7 preceding siblings ...)
2024-07-06 7:24 ` [PULL 08/13] qapi: nail down convention that Errors sections are lists Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 10/13] qapi: update prose in note blocks Markus Armbruster
` (4 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow, Stefan Hajnoczi
From: John Snow <jsnow@redhat.com>
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. Markup is also re-aligned to
the de-facto standard of 3 spaces for directives.
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 ...
... dolor sit amet ...
... consectetur adipiscing elit ...
... 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. Several instances of "Notes:" have been converted to
merely ".. note::", or multiple ".. note::" where appropriate.
".. 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. Two "Note:" following "Example:"
have been turned into ordinary paragraphs within the example.
NOTE: Because qapidoc.py does not attempt to preserve source ordering of
sections, the conversion of Notes from a "tagged section" to an
"untagged section" means that rendering order for some notes *may
change* as a result of this patch. The forthcoming qapidoc.py rewrite
strictly preserves source ordering in the rendered documentation, so
this issue will be rectified in the new generator.
Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
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 | 14 +--
qapi/misc.json | 88 +++++++++----------
qapi/net.json | 6 +-
qapi/pci.json | 8 +-
qapi/qdev.json | 28 +++---
qapi/qom.json | 17 ++--
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 | 4 +-
tests/qapi-schema/doc-good.out | 8 +-
tests/qapi-schema/doc-good.txt | 10 +--
.../qapi-schema/doc-interleaved-section.json | 2 +-
30 files changed, 261 insertions(+), 253 deletions(-)
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index cee43222f1..ae97b335cb 100644
--- a/docs/devel/qapi-code-gen.rst
+++ b/docs/devel/qapi-code-gen.rst
@@ -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
diff --git a/qapi/block-core.json b/qapi/block-core.json
index df5e07debd..cacedfb771 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -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
##
diff --git a/qapi/block.json b/qapi/block.json
index 5de99fe09d..ea81d9e192 100644
--- a/qapi/block.json
+++ b/qapi/block.json
@@ -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
#
diff --git a/qapi/char.json b/qapi/char.json
index 777dde55d9..5eabf8e764 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -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
#
diff --git a/qapi/control.json b/qapi/control.json
index 10c906fa0e..59d5e00c15 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -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 }
diff --git a/qapi/dump.json b/qapi/dump.json
index 2fa9504d86..f9aee7ea1d 100644
--- a/qapi/dump.json
+++ b/qapi/dump.json
@@ -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
#
diff --git a/qapi/introspect.json b/qapi/introspect.json
index b041b02ba8..b15052ec21 100644
--- a/qapi/introspect.json
+++ b/qapi/introspect.json
@@ -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
##
diff --git a/qapi/machine-target.json b/qapi/machine-target.json
index 2942853092..a8d9ec87f5 100644
--- a/qapi/machine-target.json
+++ b/qapi/machine-target.json
@@ -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
##
diff --git a/qapi/machine.json b/qapi/machine.json
index a982c94503..f15ad1b43e 100644
--- a/qapi/machine.json
+++ b/qapi/machine.json
@@ -24,9 +24,9 @@
#
# @avr: since 5.1
#
-# Notes: The resulting QMP strings can be appended to the
-# "qemu-system-" prefix to produce the corresponding QEMU
-# executable name. This is true even for "qemu-system-x86_64".
+# .. note:: The resulting QMP strings can be appended to the
+# "qemu-system-" prefix to produce the corresponding QEMU executable
+# name. This is true even for "qemu-system-x86_64".
#
# Since: 3.0
##
@@ -305,8 +305,9 @@
#
# Since: 0.14
#
-# Notes: If no UUID was specified for the guest, a null UUID is
-# returned.
+# .. note:: If no UUID was specified for the guest, a null UUID is
+# returned.
+#
##
{ 'struct': 'UuidInfo', 'data': {'UUID': 'str'} }
@@ -367,10 +368,10 @@
#
# Since: 0.14
#
-# Notes: A guest may or may not respond to this command. This command
-# returning does not indicate that a guest has accepted the
-# request or that it has shut down. Many guests will respond to
-# this command by prompting the user in some way.
+# .. note:: A guest may or may not respond to this command. This
+# command returning does not indicate that a guest has accepted the
+# request or that it has shut down. Many guests will respond to this
+# command by prompting the user in some way.
#
# Example:
#
@@ -389,8 +390,8 @@
#
# Since: 1.1
#
-# Note: prior to 4.0, this command does nothing in case the guest
-# isn't suspended.
+# .. note:: Prior to 4.0, this command does nothing in case the guest
+# isn't suspended.
#
# Example:
#
@@ -440,8 +441,8 @@
#
# Since: 0.14
#
-# Note: prior to 2.1, this command was only supported for x86 and s390
-# VMs
+# .. note:: Prior to 2.1, this command was only supported for x86 and
+# s390 VMs.
#
# Example:
#
@@ -839,7 +840,7 @@
#
# Since: 0.14
#
-# Notes: Errors were not reliably returned until 1.1
+# .. caution:: Errors were not reliably returned until 1.1.
#
# Example:
#
@@ -865,7 +866,7 @@
#
# Since: 0.14
#
-# Notes: Errors were not reliably returned until 1.1
+# .. caution:: Errors were not reliably returned until 1.1.
#
# Example:
#
@@ -995,8 +996,8 @@
#
# @thread-id: thread number within the core the CPU belongs to
#
-# Note: management should be prepared to pass through additional
-# properties with device_add.
+# .. note:: Management should be prepared to pass through additional
+# properties with device_add.
#
# Since: 2.7
##
@@ -1123,9 +1124,9 @@
# the KVM kernel module cannot support it, KVMMissingCap
# - If no balloon device is present, DeviceNotActive
#
-# Notes: This command just issues a request to the guest. When it
-# returns, the balloon size may not have changed. A guest can
-# change the balloon size independent of this command.
+# .. note:: This command just issues a request to the guest. When it
+# returns, the balloon size may not have changed. A guest can change
+# the balloon size independent of this command.
#
# Since: 0.14
#
@@ -1185,7 +1186,7 @@
# @actual: the logical size of the VM in bytes Formula used:
# logical_vm_size = vm_ram_size - balloon_size
#
-# Note: this event is rate-limited.
+# .. note:: This event is rate-limited.
#
# Since: 1.2
#
@@ -1248,7 +1249,7 @@
# Emitted when the hv-balloon driver receives a "STATUS" message from
# the guest.
#
-# Note: this event is rate-limited.
+# .. note:: This event is rate-limited.
#
# Since: 8.2
#
@@ -1593,7 +1594,7 @@
#
# @qom-path: path to the device object in the QOM tree (since 6.2)
#
-# Note: this event is rate-limited.
+# .. note:: This event is rate-limited.
#
# Since: 5.1
#
diff --git a/qapi/migration.json b/qapi/migration.json
index 9ec9ef36c4..1234bef888 100644
--- a/qapi/migration.json
+++ b/qapi/migration.json
@@ -1456,8 +1456,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
#
@@ -1589,16 +1589,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)
+# 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
@@ -1672,7 +1672,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
diff --git a/qapi/misc.json b/qapi/misc.json
index 4b41e15dcd..13ea82f525 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -103,9 +103,9 @@
#
# 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
-# always the main thread of the process.
+# .. note:: This list excludes the QEMU main loop thread, which is not
+# 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
#
@@ -136,13 +136,13 @@
#
# Since: 0.14
#
-# Notes: 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.
+# .. 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.
#
-# In the "suspended" state, it will completely stop the VM and
-# cause a transition to the "paused" state. (Since 9.0)
+# In the "suspended" state, it will completely stop the VM and cause
+# a transition to the "paused" state. (Since 9.0)
#
# Example:
#
@@ -158,15 +158,15 @@
#
# Since: 0.14
#
-# Notes: 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 command line option if it was passed.
+# .. 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
+# command line option if it was passed.
#
-# If the VM was previously suspended, and not been reset or woken,
-# this command will transition back to the "suspended" state.
-# (Since 9.0)
+# If the VM was previously suspended, and not been reset or woken,
+# this command will transition back to the "suspended" state. (Since
+# 9.0)
#
# Example:
#
@@ -219,18 +219,18 @@
#
# Since: 0.14
#
-# Notes: This command only exists as a stop-gap. Its use is highly
-# discouraged. The semantics of this command are not guaranteed:
-# this means that command names, arguments and responses can
-# change or be removed at ANY time. Applications that rely on
-# long term stability guarantees should NOT use this command.
+# .. note:: This command only exists as a stop-gap. Its use is highly
+# discouraged. The semantics of this command are not guaranteed:
+# this means that command names, arguments and responses can change
+# or be removed at ANY time. Applications that rely on long term
+# stability guarantees should NOT use this command.
#
-# Known limitations:
+# Known limitations:
#
-# * This command is stateless, this means that commands that
-# depend on state information (such as getfd) might not work
+# * This command is stateless, this means that commands that
+# depend on state information (such as getfd) might not work.
#
-# * Commands that prompt the user for data don't currently work
+# * Commands that prompt the user for data don't currently work.
#
# Example:
#
@@ -252,11 +252,11 @@
#
# Since: 0.14
#
-# Notes: If @fdname already exists, the file descriptor assigned to it
-# will be closed and replaced by the received file descriptor.
+# .. note:: If @fdname already exists, the file descriptor assigned to
+# it will be closed and replaced by the received file descriptor.
#
-# The 'closefd' command can be used to explicitly close the file
-# descriptor when it is no longer needed.
+# The 'closefd' command can be used to explicitly close the file
+# descriptor when it is no longer needed.
#
# Example:
#
@@ -279,11 +279,11 @@
#
# Since: 8.0
#
-# Notes: If @fdname already exists, the file descriptor assigned to it
-# will be closed and replaced by the received file descriptor.
+# .. note:: If @fdname already exists, the file descriptor assigned to
+# it will be closed and replaced by the received file descriptor.
#
-# The 'closefd' command can be used to explicitly close the file
-# descriptor when it is no longer needed.
+# The 'closefd' command can be used to explicitly close the file
+# descriptor when it is no longer needed.
#
# Example:
#
@@ -339,10 +339,9 @@
# - If file descriptor was not received, GenericError
# - If @fdset-id is a negative value, GenericError
#
-# Notes:
-# The list of fd sets is shared by all monitor connections.
+# .. note:: The list of fd sets is shared by all monitor connections.
#
-# If @fdset-id is not specified, a new fd set will be created.
+# .. note:: If @fdset-id is not specified, a new fd set will be created.
#
# Since: 1.2
#
@@ -370,11 +369,10 @@
#
# Since: 1.2
#
-# Notes:
-# The list of fd sets is shared by all monitor connections.
+# .. note:: The list of fd sets is shared by all monitor connections.
#
-# If @fd is not specified, all file descriptors in @fdset-id will
-# be removed.
+# .. note:: If @fd is not specified, all file descriptors in @fdset-id
+# will be removed.
#
# Example:
#
@@ -420,7 +418,7 @@
#
# Since: 1.2
#
-# Note: The list of fd sets is shared by all monitor connections.
+# .. note:: The list of fd sets is shared by all monitor connections.
#
# Example:
#
@@ -561,9 +559,9 @@
#
# @qom-path: path to the RTC object in the QOM tree
#
-# Note: This event is rate-limited. It is not guaranteed that the RTC
-# in the system implements this event, or even that the system has
-# an RTC at all.
+# .. note:: This event is rate-limited. It is not guaranteed that the
+# RTC in the system implements this event, or even that the system
+# has an RTC at all.
#
# Since: 0.13
#
diff --git a/qapi/net.json b/qapi/net.json
index c19df435a5..dd6c365c34 100644
--- a/qapi/net.json
+++ b/qapi/net.json
@@ -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:
#
diff --git a/qapi/pci.json b/qapi/pci.json
index 08bf695863..8287d15dd0 100644
--- a/qapi/pci.json
+++ b/qapi/pci.json
@@ -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,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'] }
diff --git a/qapi/qdev.json b/qapi/qdev.json
index facaa0bc6a..f5b35a814f 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -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
#
diff --git a/qapi/qom.json b/qapi/qom.json
index 92b0fea76c..8e75a419c3 100644
--- a/qapi/qom.json
+++ b/qapi/qom.json
@@ -195,9 +195,9 @@
#
# @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.
+# .. 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
#
@@ -614,12 +614,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
##
diff --git a/qapi/rocker.json b/qapi/rocker.json
index f5225eb62c..9f95e63830 100644
--- a/qapi/rocker.json
+++ b/qapi/rocker.json
@@ -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
##
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 5ac0fec852..30cd25d3c9 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -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
#
diff --git a/qapi/sockets.json b/qapi/sockets.json
index aa97c89768..3970118bf4 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -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
##
diff --git a/qapi/stats.json b/qapi/stats.json
index 578b52c7ef..efbbe26244 100644
--- a/qapi/stats.json
+++ b/qapi/stats.json
@@ -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
##
diff --git a/qapi/transaction.json b/qapi/transaction.json
index 07afc269d5..bcb05fdedd 100644
--- a/qapi/transaction.json
+++ b/qapi/transaction.json
@@ -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
#
diff --git a/qapi/ui.json b/qapi/ui.json
index c12f529257..a1999965e4 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -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:
#
diff --git a/qapi/virtio.json b/qapi/virtio.json
index 74fc27c702..b91f3cdd0d 100644
--- a/qapi/virtio.json
+++ b/qapi/virtio.json
@@ -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
#
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index b3de1fb6b3..57598331c5 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -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,
+# @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.
#
# Since: 2.10
##
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index c3d20cc01b..0a13f0f541 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -547,6 +547,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:
diff --git a/tests/qapi-schema/doc-empty-section.err b/tests/qapi-schema/doc-empty-section.err
index 5f03a6d733..711a0d629c 100644
--- a/tests/qapi-schema/doc-empty-section.err
+++ b/tests/qapi-schema/doc-empty-section.err
@@ -1 +1 @@
-doc-empty-section.json:6: text required after 'Note:'
+doc-empty-section.json:6: text required after 'Errors:'
diff --git a/tests/qapi-schema/doc-empty-section.json b/tests/qapi-schema/doc-empty-section.json
index f3384e9a3b..f179d3eff6 100644
--- a/tests/qapi-schema/doc-empty-section.json
+++ b/tests/qapi-schema/doc-empty-section.json
@@ -3,6 +3,6 @@
##
# @foo:
#
-# Note:
+# Errors:
##
{ 'command': 'foo', 'data': {'a': 'int'} }
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 8b39eb946a..32ff910b4f 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -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
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 435f6e6d76..631dc9f8da 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -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
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index 847db70412..d8bfa742c2 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -193,11 +193,9 @@ Features
"cmd-feat2"
another feature
+Note:
-Note
-~~~~
-
-"arg3" is undocumented
+ "arg3" is undocumented
Returns
@@ -211,9 +209,7 @@ Errors
some
-
-Notes
-~~~~~
+Notes:
* Lorem ipsum dolor sit amet
diff --git a/tests/qapi-schema/doc-interleaved-section.json b/tests/qapi-schema/doc-interleaved-section.json
index adb29e98da..eec01ed565 100644
--- a/tests/qapi-schema/doc-interleaved-section.json
+++ b/tests/qapi-schema/doc-interleaved-section.json
@@ -10,7 +10,7 @@
#
# bao
#
-# Note: a section.
+# TODO: a section.
#
# @foobar: catch this
#
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 10/13] qapi: update prose in note blocks
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (8 preceding siblings ...)
2024-07-06 7:24 ` [PULL 09/13] qapi: convert "Note" sections to plain rST Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 11/13] qapi: add markup to " Markus Armbruster
` (3 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
Where I've noticed, rephrase the note to read more fluently.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-12-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
qapi/block-core.json | 4 ++--
qga/qapi-schema.json | 2 +-
2 files changed, 3 insertions(+), 3 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index cacedfb771..9ef23ec02a 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -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
##
diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
index 57598331c5..1273d85bb5 100644
--- a/qga/qapi-schema.json
+++ b/qga/qapi-schema.json
@@ -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.
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 11/13] qapi: add markup to note blocks
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (9 preceding siblings ...)
2024-07-06 7:24 ` [PULL 10/13] qapi: update prose in note blocks Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 12/13] qapi/parser: don't parse rST markup as section headers Markus Armbruster
` (2 subsequent siblings)
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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.
Signed-off-by: John Snow <jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240626222128.406106-13-jsnow@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
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(-)
diff --git a/qapi/control.json b/qapi/control.json
index 59d5e00c15..fe2af45120 100644
--- a/qapi/control.json
+++ b/qapi/control.json
@@ -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.
diff --git a/qapi/misc.json b/qapi/misc.json
index 13ea82f525..b04efbadec 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -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,
diff --git a/qapi/qdev.json b/qapi/qdev.json
index f5b35a814f..d031fc3590 100644
--- a/qapi/qdev.json
+++ b/qapi/qdev.json
@@ -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:
diff --git a/qapi/run-state.json b/qapi/run-state.json
index 30cd25d3c9..4d40c88876 100644
--- a/qapi/run-state.json
+++ b/qapi/run-state.json
@@ -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.
#
diff --git a/qapi/sockets.json b/qapi/sockets.json
index 3970118bf4..4d78d2ccb7 100644
--- a/qapi/sockets.json
+++ b/qapi/sockets.json
@@ -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
##
diff --git a/qapi/ui.json b/qapi/ui.json
index a1999965e4..5bcccbfc93 100644
--- a/qapi/ui.json
+++ b/qapi/ui.json
@@ -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.
#
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 12/13] qapi/parser: don't parse rST markup as section headers
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (10 preceding siblings ...)
2024-07-06 7:24 ` [PULL 11/13] qapi: add markup to " Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-06 7:24 ` [PULL 13/13] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments Markus Armbruster
2024-07-08 15:18 ` [PULL 00/13] QAPI patches patches for 2024-07-06 Richard Henderson
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, John Snow
From: John Snow <jsnow@redhat.com>
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.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240626222128.406106-14-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Indentation tweaked for consistency]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
scripts/qapi/parser.py | 9 +++++++--
tests/qapi-schema/doc-good.json | 3 +++
tests/qapi-schema/doc-good.out | 3 +++
tests/qapi-schema/doc-good.txt | 3 +++
4 files changed, 16 insertions(+), 2 deletions(-)
diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
index 0a13f0f541..6ad5663e54 100644
--- a/scripts/qapi/parser.py
+++ b/scripts/qapi/parser.py
@@ -544,10 +544,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.
diff --git a/tests/qapi-schema/doc-good.json b/tests/qapi-schema/doc-good.json
index 32ff910b4f..b565895858 100644
--- a/tests/qapi-schema/doc-good.json
+++ b/tests/qapi-schema/doc-good.json
@@ -181,6 +181,9 @@
# - *verbatim*
# - {braces}
#
+# Note::
+# Ceci n'est pas une note
+#
# Since: 2.10
##
{ 'command': 'cmd',
diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
index 631dc9f8da..a8e9456f60 100644
--- a/tests/qapi-schema/doc-good.out
+++ b/tests/qapi-schema/doc-good.out
@@ -190,6 +190,9 @@ frobnicate
section=Examples
- *verbatim*
- {braces}
+ section=None
+Note::
+ Ceci n'est pas une note
section=Since
2.10
doc symbol=cmd-boxed
diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt
index d8bfa742c2..30d457e548 100644
--- a/tests/qapi-schema/doc-good.txt
+++ b/tests/qapi-schema/doc-good.txt
@@ -231,6 +231,9 @@ Examples
- *verbatim*
- {braces}
+Note::
+ Ceci n'est pas une note
+
Since
~~~~~
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* [PULL 13/13] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (11 preceding siblings ...)
2024-07-06 7:24 ` [PULL 12/13] qapi/parser: don't parse rST markup as section headers Markus Armbruster
@ 2024-07-06 7:24 ` Markus Armbruster
2024-07-08 15:18 ` [PULL 00/13] QAPI patches patches for 2024-07-06 Richard Henderson
13 siblings, 0 replies; 15+ messages in thread
From: Markus Armbruster @ 2024-07-06 7:24 UTC (permalink / raw)
To: qemu-devel; +Cc: richard.henderson, qemu-stable, John Snow
When a command's arguments are specified as an explicit type T,
generated documentation points to the members of T.
Example:
##
# @announce-self:
#
# Trigger generation of broadcast RARP frames to update network
[...]
##
{ 'command': 'announce-self', 'boxed': true,
'data' : 'AnnounceParameters'}
generates
"announce-self" (Command)
-------------------------
Trigger generation of broadcast RARP frames to update network
[...]
Arguments
~~~~~~~~~
The members of "AnnounceParameters"
Except when the command takes its arguments unboxed , i.e. it doesn't
have 'boxed': true, we generate *nothing*. A few commands have a
reference in their doc comment to compensate, but most don't.
Example:
##
# @blockdev-snapshot-sync:
#
# Takes a synchronous snapshot of a block device.
#
# For the arguments, see the documentation of BlockdevSnapshotSync.
[...]
##
{ 'command': 'blockdev-snapshot-sync',
'data': 'BlockdevSnapshotSync',
'allow-preconfig': true }
generates
"blockdev-snapshot-sync" (Command)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Takes a synchronous snapshot of a block device.
For the arguments, see the documentation of BlockdevSnapshotSync.
[...]
Same for event data.
Fix qapidoc.py to generate the reference regardless of boxing. Delete
now redundant references in the doc comments.
Fixes: 4078ee5469e5 (docs/sphinx: Add new qapi-doc Sphinx extension)
Cc: qemu-stable@nongnu.org
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240628112756.794237-1-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
---
docs/sphinx/qapidoc.py | 12 +++++-------
qapi/block-core.json | 7 -------
2 files changed, 5 insertions(+), 14 deletions(-)
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
index efcd84656f..2b06750a3c 100644
--- a/docs/sphinx/qapidoc.py
+++ b/docs/sphinx/qapidoc.py
@@ -230,15 +230,15 @@ def _nodes_for_enum_values(self, doc):
section += dlnode
return [section]
- def _nodes_for_arguments(self, doc, boxed_arg_type):
+ def _nodes_for_arguments(self, doc, arg_type):
"""Return list of doctree nodes for the arguments section"""
- if boxed_arg_type:
+ if arg_type and not arg_type.is_implicit():
assert not doc.args
section = self._make_section('Arguments')
dlnode = nodes.definition_list()
dlnode += self._make_dlitem(
[nodes.Text('The members of '),
- nodes.literal('', boxed_arg_type.name)],
+ nodes.literal('', arg_type.name)],
None)
section += dlnode
return [section]
@@ -352,8 +352,7 @@ def visit_command(self, name, info, ifcond, features, arg_type,
allow_preconfig, coroutine):
doc = self._cur_doc
self._add_doc('Command',
- self._nodes_for_arguments(doc,
- arg_type if boxed else None)
+ self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
@@ -361,8 +360,7 @@ def visit_command(self, name, info, ifcond, features, arg_type,
def visit_event(self, name, info, ifcond, features, arg_type, boxed):
doc = self._cur_doc
self._add_doc('Event',
- self._nodes_for_arguments(doc,
- arg_type if boxed else None)
+ self._nodes_for_arguments(doc, arg_type)
+ self._nodes_for_features(doc)
+ self._nodes_for_sections(doc)
+ self._nodes_for_if_section(ifcond))
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 9ef23ec02a..096bdbe0aa 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1675,8 +1675,6 @@
#
# Takes a synchronous snapshot of a block device.
#
-# For the arguments, see the documentation of BlockdevSnapshotSync.
-#
# Errors:
# - If @device is not a valid block device, DeviceNotFound
#
@@ -1705,8 +1703,6 @@
# device, the block device changes to using 'overlay' as its new
# active image.
#
-# For the arguments, see the documentation of BlockdevSnapshot.
-#
# Features:
#
# @allow-write-only-overlay: If present, the check whether this
@@ -6065,9 +6061,6 @@
# string, or a snapshot with name already exists, the operation will
# fail.
#
-# For the arguments, see the documentation of
-# BlockdevSnapshotInternal.
-#
# Errors:
# - If @device is not a valid block device, GenericError
# - If any snapshot matching @name exists, or @name is empty,
--
2.45.0
^ permalink raw reply related [flat|nested] 15+ messages in thread
* Re: [PULL 00/13] QAPI patches patches for 2024-07-06
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
` (12 preceding siblings ...)
2024-07-06 7:24 ` [PULL 13/13] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments Markus Armbruster
@ 2024-07-08 15:18 ` Richard Henderson
13 siblings, 0 replies; 15+ messages in thread
From: Richard Henderson @ 2024-07-08 15:18 UTC (permalink / raw)
To: Markus Armbruster, qemu-devel
On 7/6/24 00:24, Markus Armbruster wrote:
> The following changes since commit f2cb4026fccfe073f84a4b440e41d3ed0c3134f6:
>
> Merge tag 'pull-maintainer-july24-050724-1' ofhttps://gitlab.com/stsquad/qemu into staging (2024-07-05 09:15:48 -0700)
>
> are available in the Git repository at:
>
> https://repo.or.cz/qemu/armbru.git tags/pull-qapi-2024-07-06
>
> for you to fetch changes up to e389929d19a543ea5b34d02553b355f9f1c03162:
>
> sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments (2024-07-06 08:58:24 +0200)
>
> ----------------------------------------------------------------
> QAPI patches patches for 2024-07-06
Applied, thanks.
r~
^ permalink raw reply [flat|nested] 15+ messages in thread
end of thread, other threads:[~2024-07-08 15:20 UTC | newest]
Thread overview: 15+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-07-06 7:24 [PULL 00/13] QAPI patches patches for 2024-07-06 Markus Armbruster
2024-07-06 7:24 ` [PULL 01/13] qapi: linter fixups Markus Armbruster
2024-07-06 7:24 ` [PULL 02/13] docs/qapidoc: remove unused intersperse function Markus Armbruster
2024-07-06 7:24 ` [PULL 03/13] docs/qapidoc: delint a tiny portion of the module Markus Armbruster
2024-07-06 7:24 ` [PULL 04/13] qapi/parser: preserve indentation in QAPIDoc sections Markus Armbruster
2024-07-06 7:24 ` [PULL 05/13] qapi/parser: fix comment parsing immediately following a doc block Markus Armbruster
2024-07-06 7:24 ` [PULL 06/13] docs/qapidoc: fix nested parsing under untagged sections Markus Armbruster
2024-07-06 7:24 ` [PULL 07/13] qapi: fix non-compliant JSON examples Markus Armbruster
2024-07-06 7:24 ` [PULL 08/13] qapi: nail down convention that Errors sections are lists Markus Armbruster
2024-07-06 7:24 ` [PULL 09/13] qapi: convert "Note" sections to plain rST Markus Armbruster
2024-07-06 7:24 ` [PULL 10/13] qapi: update prose in note blocks Markus Armbruster
2024-07-06 7:24 ` [PULL 11/13] qapi: add markup to " Markus Armbruster
2024-07-06 7:24 ` [PULL 12/13] qapi/parser: don't parse rST markup as section headers Markus Armbruster
2024-07-06 7:24 ` [PULL 13/13] sphinx/qapidoc: Fix to generate doc for explicit, unboxed arguments Markus Armbruster
2024-07-08 15:18 ` [PULL 00/13] QAPI patches patches for 2024-07-06 Richard Henderson
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).