diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index f453bd3546..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 @@ -1011,6 +1010,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/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index f270b494f0..2b06750a3c 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -26,38 +26,49 @@ https://www.sphinx-doc.org/en/master/development/index.html import os import re +import textwrap 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" -# 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 +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 class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): @@ -167,7 +178,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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')] @@ -205,7 +216,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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')] @@ -219,15 +230,15 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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] @@ -240,7 +251,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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: @@ -261,11 +272,20 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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'): - snode += self._nodes_for_example(section.text) + if section.tag.startswith('Example'): + 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), snode) nodelist.append(snode) return nodelist @@ -332,8 +352,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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)) @@ -341,8 +360,7 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): 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)) @@ -451,6 +469,10 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor): return self._top_node.children +# Turn the black formatter on for the rest of the file. +# fmt: on + + class QAPISchemaGenDepVisitor(QAPISchemaVisitor): """A QAPI schema visitor which adds Sphinx dependencies each module @@ -458,34 +480,34 @@ class QAPISchemaGenDepVisitor(QAPISchemaVisitor): that the generated documentation output depends on the input schema file associated with each module in the QAPI input. """ + def __init__(self, env, qapidir): self._env = env self._qapidir = qapidir def visit_module(self, name): if name != "./builtin": - qapifile = self._qapidir + '/' + name + qapifile = self._qapidir + "/" + name self._env.note_dependency(os.path.abspath(qapifile)) super().visit_module(name) class QAPIDocDirective(Directive): """Extract documentation from the specified QAPI .json file""" + required_argument = 1 optional_arguments = 1 - option_spec = { - 'qapifile': directives.unchanged_required - } + option_spec = {"qapifile": directives.unchanged_required} has_content = False def new_serialno(self): """Return a unique new ID string suitable for use as a node's ID""" env = self.state.document.settings.env - return 'qapidoc-%d' % env.new_serialno('qapidoc') + return "qapidoc-%d" % env.new_serialno("qapidoc") def run(self): env = self.state.document.settings.env - qapifile = env.config.qapidoc_srctree + '/' + self.arguments[0] + qapifile = env.config.qapidoc_srctree + "/" + self.arguments[0] qapidir = os.path.dirname(qapifile) try: @@ -523,13 +545,14 @@ class QAPIDocDirective(Directive): # plain self.state.nested_parse(), and so we can drop the saving # of title_styles and section_level that kerneldoc.py does, # because nested_parse_with_titles() does that for us. - if Use_SSI: + if USE_SSI: with switch_source_input(self.state, rstlist): nested_parse_with_titles(self.state, rstlist, node) else: save = self.state.memo.reporter self.state.memo.reporter = AutodocReporter( - rstlist, self.state.memo.reporter) + rstlist, self.state.memo.reporter + ) try: nested_parse_with_titles(self.state, rstlist, node) finally: @@ -537,12 +560,12 @@ class QAPIDocDirective(Directive): 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, + } diff --git a/qapi/block-core.json b/qapi/block-core.json index df5e07debd..096bdbe0aa 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 ## @@ -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 @@ -5545,8 +5541,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 +5588,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 +5727,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 +5981,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 +6012,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 +6044,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 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. # # Since: 1.7 ## @@ -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, 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 6bdbf077c2..fe2af45120 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 :doc:`/interop/qmp-spec`) # -# 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 ## @@ -145,12 +144,13 @@ # }, # { # "name":"system_powerdown" -# } +# }, +# ... # ] # } # -# 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 2fd3e9c3d5..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 ## @@ -1057,7 +1058,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: # @@ -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 0f24206bce..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 @@ -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..b04efbadec 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,15 +279,16 @@ # # 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: # -# -> { "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' } @@ -338,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 # @@ -369,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: # @@ -419,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: # @@ -560,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 0f5a259475..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: # @@ -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/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..d031fc3590 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. # @@ -59,8 +59,8 @@ # 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 -# is the device's name +# the ``-device DEVICE,help`` command-line argument, where DEVICE +# 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 5635cf174f..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 ## @@ -250,7 +250,7 @@ # "action": {"goto-tbl": 10}, # "mask": {"in-pport": 4294901760} # }, -# {...more...}, +# {...}, # ]} ## { 'command': 'query-rocker-of-dpa-flows', @@ -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..4d40c88876 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..4d78d2ccb7 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 5749c133d4..bcb05fdedd 100644 --- a/qapi/transaction.json +++ b/qapi/transaction.json @@ -235,12 +235,12 @@ # 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 -# 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 f610bce118..5bcccbfc93 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 ## @@ -361,7 +360,7 @@ # "channel-id": 0, # "tls": false # }, -# [ ... more channels follow ... ] +# ... # ] # } # } @@ -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..1273d85bb5 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 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. # # 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/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 .gen import QAPISchemaMonolithicCVisitor from .schema import ( QAPISchema, QAPISchemaAlternatives, - QAPISchemaBranches, QAPISchemaArrayType, + QAPISchemaBranches, QAPISchemaBuiltinType, QAPISchemaEntity, QAPISchemaEnumMember, @@ -233,9 +233,9 @@ const QLitObject %(c_name)s = %(c_string)s; 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/parser.py b/scripts/qapi/parser.py index 7b13a583ac..6ad5663e54 100644 --- a/scripts/qapi/parser.py +++ b/scripts/qapi/parser.py @@ -448,7 +448,7 @@ class QAPISchemaParser: 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 @@ class QAPISchemaParser: 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]: @@ -544,9 +544,29 @@ class QAPISchemaParser: 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. + + # 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: @@ -583,7 +603,7 @@ class QAPISchemaParser: line = self.get_doc_line() first = False - self.accept(False) + self.accept() doc.end() return doc 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 @@ class QAPISchemaVariants: 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 @@ class QAPISchema: 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 @@ class QAPISchema: 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 @@ bool visit_type_%(c_name)s(Visitor *v, const char *name, 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; 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 de38a386e8..b565895858 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: # @@ -155,7 +157,7 @@ # @cmd-feat1: a feature # @cmd-feat2: another feature # -# Note: @arg3 is undocumented +# .. note:: @arg3 is undocumented # # Returns: @Object # @@ -163,7 +165,7 @@ # # TODO: frobnicate # -# Notes: +# .. admonition:: Notes # # - Lorem ipsum dolor sit amet # - Ut enim ad minim veniam @@ -179,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 716a9a4102..a8e9456f60 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,36 +158,41 @@ 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 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 -- Lorem ipsum dolor sit amet -- Ut enim ad minim veniam + section=None +.. admonition:: Notes -Duis aute irure dolor + - Lorem ipsum dolor sit amet + - Ut enim ad minim veniam + + Duis aute irure dolor section=Example --> in -<- out + -> in + <- out section=Examples -- *verbatim* -- {braces} + - *verbatim* + - {braces} + section=None +Note:: + Ceci n'est pas une note section=Since 2.10 doc symbol=cmd-boxed @@ -198,9 +203,9 @@ a feature feature=cmd-feat2 another feature section=Example --> in + -> in -<- out + <- out doc symbol=EVT_BOXED body= diff --git a/tests/qapi-schema/doc-good.txt b/tests/qapi-schema/doc-good.txt index 847db70412..30d457e548 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 @@ -235,6 +231,9 @@ Examples - *verbatim* - {braces} +Note:: + Ceci n'est pas une note + Since ~~~~~ 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 #