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 @@ class QAPISchemaParser: 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 #