Re: [PATCH 19/20] qapi: convert "Note" sections to plain rST

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 58787 bytes --]

On Fri, Jun 14, 2024, 9:44 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > We do not need a dedicated section for notes. By eliminating a specially
> > parsed section, these notes can be treated as normal rST paragraphs in
> > the new QMP reference manual, and can be placed and styled much more
> > flexibly.
> >
> > Update the QAPI parser to now prohibit special "Note" sections while
> > suggesting a new syntax.
> >
> > The exact formatting to use is a matter of taste, but a good candidate
> > is simply:
> >
> > .. note:: lorem ipsum ...
> >
> > but there are other choices, too. The Sphinx readthedocs theme offers
> > theming for the following forms (capitalization unimportant); all are
> > adorned with a (!) symbol in the title bar for rendered HTML docs.
>

Store this paragraph in your L1 cache for a moment ...

>
> > These are rendered in orange:
> >
> > .. Attention:: ...
> > .. Caution:: ...
> > .. WARNING:: ...
> >
> > These are rendered in red:
> >
> > .. DANGER:: ...
> > .. Error:: ...
> >
> > These are rendered in green:
> >
> > .. Hint:: ...
> > .. Important:: ...
> > .. Tip:: ...
> >
> > These are rendered in blue:
> >
> > .. Note:: ...
> > .. admonition:: custom title
> >
> >    admonition body text
> >
> > This patch uses ".. notes::" almost everywhere, with just two "caution"
> > directives. ".. admonition:: notes" is used in a few places where we had
> > an ordered list of multiple notes.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> >  qapi/block-core.json                          | 30 +++----
> >  qapi/block.json                               |  2 +-
> >  qapi/char.json                                | 12 +--
> >  qapi/control.json                             | 15 ++--
> >  qapi/dump.json                                |  2 +-
> >  qapi/introspect.json                          |  6 +-
> >  qapi/machine-target.json                      | 26 +++---
> >  qapi/machine.json                             | 47 +++++-----
> >  qapi/migration.json                           | 12 +--
> >  qapi/misc.json                                | 88 +++++++++----------
> >  qapi/net.json                                 |  6 +-
> >  qapi/pci.json                                 |  7 +-
> >  qapi/qdev.json                                | 30 +++----
> >  qapi/qom.json                                 | 19 ++--
> >  qapi/rocker.json                              | 16 ++--
> >  qapi/run-state.json                           | 18 ++--
> >  qapi/sockets.json                             | 10 +--
> >  qapi/stats.json                               | 22 ++---
> >  qapi/transaction.json                         |  8 +-
> >  qapi/ui.json                                  | 29 +++---
> >  qapi/virtio.json                              | 12 +--
> >  qga/qapi-schema.json                          | 48 +++++-----
> >  scripts/qapi/parser.py                        |  9 ++
> >  tests/qapi-schema/doc-empty-section.err       |  2 +-
> >  tests/qapi-schema/doc-empty-section.json      |  2 +-
> >  tests/qapi-schema/doc-good.json               |  6 +-
> >  tests/qapi-schema/doc-good.out                | 10 ++-
> >  tests/qapi-schema/doc-good.txt                | 14 ++-
> >  .../qapi-schema/doc-interleaved-section.json  |  2 +-
> >  29 files changed, 258 insertions(+), 252 deletions(-)
>
> Missing: update of docs/devel/qapi-code-gen.rst.  Something like
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index f453bd3546..1a4e240adb 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
>
>
Done.


> >
> > diff --git a/qapi/block-core.json b/qapi/block-core.json
> > index 64fe5240cc9..530af40404d 100644
> > --- a/qapi/block-core.json
> > +++ b/qapi/block-core.json
> > @@ -1510,7 +1510,7 @@
> >  # @mode: whether and how QEMU should create a new image, default is
> >  #     'absolute-paths'.
> >  #
> > -# Note: Either @device or @node-name must be set but not both.
> > +# .. note:: Either @device or @node-name must be set but not both.
>
> The commit message talks about ".. Note::", but you actually use
> ".. note::".  Is there a difference?
>

Retrieve paragraph from L1 cache.

Nope! Sphinx RTD theme docs use capitals sporadically, but it's case
insensitive. I stuck with all lowercase everywhere in the patches, but the
capitalization in the commit message came directly from the Sphinx RTD
theme documentation.


> >  #
> >  ##
> >  { 'struct': 'BlockdevSnapshotSync',
> > @@ -1616,9 +1616,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
> >  ##
> > @@ -5534,8 +5534,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:
> >  #
> > @@ -5581,8 +5581,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.
>
> You're adding a period.  Okay, but please mention it in the commit
> message.
>

OK. When hoisting notes into little visual boxes I felt it looked naked
without the punctuation, so I just went for it. Sorry.


> >  #
> >  # Since: 0.13
> >  #
> > @@ -5720,8 +5720,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.
>
> Likewise.  Not going to point this out again.
>

I just need to update the commit message, yeah?.


> >  #
> >  # Since: 1.3
> >  #
> > @@ -5974,7 +5974,7 @@
> >  #
> >  # @sectors-count: failed read operation sector count
> >  #
> > -# Note: This event is rate-limited.
> > +# .. note:: This event is rate-limited.
> >  #
> >  # Since: 2.0
> >  #
> > @@ -6005,7 +6005,7 @@
> >  #
> >  # @sectors-count: failed read operation sector count
> >  #
> > -# Note: This event is rate-limited.
> > +# .. note:: This event is rate-limited.
> >  #
> >  # Since: 2.0
> >  #
> > @@ -6037,9 +6037,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.
>
> You're fixing up prose.  Welcome, but put it in a separate patch,
> please, to keep this one mechanical.
>

Couldn't help it while auditing every last notebox. (:

OK, separate patch...


> >  #
> >  # Since: 1.7
> >  ##
> > diff --git a/qapi/block.json b/qapi/block.json
> > index 5de99fe09d9..ea81d9e1921 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 ab4c23976ed..0f39c2d5cdf 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
> >  ##
> > @@ -387,9 +387,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.
>
> You're capitalizing the beginning of the note text.  Good, because the
> generated HTML wants that.  But please mention it in the commit message.
>
> More below; not going to point it out.
>

OK; so long as the commit message mentions it, we don't need to make note
of each time I do it, right...?


> >  #
> >  # Since: 1.5
> >  ##
> > @@ -805,7 +805,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 10c906fa0e7..2498e5dd6ba 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`)
>
> You're adding markup to make a reference work.  Welcome, but put it in a
> separate patch, please, to keep this one mechanical.
>

Whoops. This snuck in. I do have a growing markup change patch...


> >  #
> > -#     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,7 +149,7 @@
> >  #          ]
> >  #        }
> >  #
> > -# Note: This example has been shortened as the real response is too
> > +#     Note: This example has been shortened as the real response is too
> >  #     long.
>
> Your commit message lists a number of conversions.  This one isn't among
> them.
>
> The next patch reverts the indentation and drops "Note: ":
>
>    -#     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.
>
> Hmm.  Swap the two patches?  Perhaps not worth the bother now.  Squash
> the next patch's change into this one?
>

Yeah, OK. (The problem was that this began being picked up as a note
section in its own right, but I thought it wasn't appropriate in this case,
but needed to avoid the parser complaining about the old Note: section.)


> A few more below.
>
> >  ##
> >  { 'command': 'query-commands', 'returns': ['CommandInfo'],
> > diff --git a/qapi/dump.json b/qapi/dump.json
> > index 2fa9504d864..f9aee7ea1dd 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 b041b02ba8c..b15052ec21a 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 29428530923..a8d9ec87f59 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 35cca12ba41..e9c9bef940d 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:
> >  #
> > @@ -838,7 +839,7 @@
> >  #
> >  # Since: 0.14
> >  #
> > -# Notes: Errors were not reliably returned until 1.1
> > +# .. caution:: Errors were not reliably returned until 1.1.
> >  #
> >  # Example:
> >  #
> > @@ -864,7 +865,7 @@
> >  #
> >  # Since: 0.14
> >  #
> > -# Notes: Errors were not reliably returned until 1.1
> > +# .. caution:: Errors were not reliably returned until 1.1.
> >  #
> >  # Example:
> >  #
> > @@ -994,8 +995,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
> >  ##
> > @@ -1122,9 +1123,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
> >  #
> > @@ -1184,7 +1185,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
> >  #
> > @@ -1246,7 +1247,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
> >  #
> > @@ -1591,7 +1592,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 89047d46c7c..a7b8ff138e3 100644
> > --- a/qapi/migration.json
> > +++ b/qapi/migration.json
> > @@ -1428,8 +1428,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
> >  #
> > @@ -1561,16 +1561,16 @@
> >  #
> >  # Since: 0.14
> >  #
> > -# Notes:
> > +# .. admonition:: Notes
> >  #
> >  #     1. The 'query-migrate' command should be used to check
> >  #        migration's progress and final result (this information is
> >  #        provided by the 'status' member)
> >  #
> > -#     2. All boolean arguments default to false
> > +#     2. All boolean arguments default to false.
> >  #
> >  #     3. The user Monitor's "detach" argument is invalid in QMP and
> > -#        should not be used
> > +#        should not be used.
> >  #
> >  #     4. The uri argument should have the Uniform Resource Identifier
> >  #        of default destination VM. This connection will be bound to
> > @@ -1644,7 +1644,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 4b41e15dcd4..b04efbadec6 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.
>
> You're adding markup.  Welcome, but put it in a separate patch, please,
> to keep this one mechanical.
>

OK


> >  #
> >  # 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.
>
> Likewise.
>

;_;


> >  #
> > -#     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.
>
> Likewise.
>
> >  #
> > -#     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 dc616d010f0..4ac7fdc7e6c 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 08bf6958634..f51159a2c4c 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,8 @@
> >  #           ]
> >  #        }
> >  #
> > -# Note: This example has been shortened as the real response is too
> > +#     Note: This example has been shortened as the real response is too
> >  #     long.
> > +#
> >  ##
> >  { 'command': 'query-pci', 'returns': ['PciInfo'] }
> > diff --git a/qapi/qdev.json b/qapi/qdev.json
> > index facaa0bc6a2..d031fc3590d 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.
>
> Likewise.
>
> >  #
> >  # 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 8f0601859b1..e927f4a3c5d 100644
> > --- a/qapi/qom.json
> > +++ b/qapi/qom.json
> > @@ -195,12 +195,12 @@
> >  #
> >  # @typename: the type name of an object
> >  #
> > -# Note: objects can create properties at runtime, for example to
> > -#     describe links between different devices and/or objects.  These
> > -#     properties are not included in the output of this command.
> > -#
> >  # Returns: a list of ObjectPropertyInfo describing object properties
> >  #
> > +# .. note:: Objects can create properties at runtime, for example to
> > +#    describe links between different devices and/or objects.  These
> > +#    properties are not included in the output of this command.
> > +#
> >  # Since: 2.12
> >  ##
> >  { 'command': 'qom-list-properties',
> > @@ -608,12 +608,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 f5225eb62cc..9f95e638309 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 f8773f23b29..252d7d6afa7 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.
>
> Likewise.
>
> >  #
> >  # 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 aa97c897687..f46113ab1b8 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.
>
> Likewise.
>
> >  #
> >  # Since: 1.3
> >  ##
> > diff --git a/qapi/stats.json b/qapi/stats.json
> > index c4a9f3ff70e..683929b2322 100644
> > --- a/qapi/stats.json
> > +++ b/qapi/stats.json
> > @@ -254,17 +254,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 07afc269d54..bcb05fdedd6 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 2d0aa407aca..ec72998e28e 100644
> > --- a/qapi/ui.json
> > +++ b/qapi/ui.json
> > @@ -103,11 +103,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
> >  ##
> > @@ -268,7 +267,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
> >  ##
> > @@ -697,9 +696,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' },
> > @@ -714,8 +713,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
> >  #
> > @@ -1260,10 +1259,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.
>
> Likewise.
>
> >  #
> >  # Examples:
> >  #
> > diff --git a/qapi/virtio.json b/qapi/virtio.json
> > index 74fc27c7029..b91f3cdd0df 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 b3de1fb6b3a..1273d85bb5f 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.
>
> Prose again.
>

Okey dokey.


> >  #
> >  # 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.
>
> Accidental indentation change?
>

I don't think so; the original heading seems to suggest that there is a
sequence of notes; "On POSIX" ... "On Windows". This indentation change
keeps this information in the same note box.


> >  #
> >  # Since: 2.10
> >  ##
> > diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> > index 3cd8e7ee295..8b1da96124e 100644
> > --- a/scripts/qapi/parser.py
> > +++ b/scripts/qapi/parser.py
> > @@ -557,6 +557,15 @@ def get_doc(self) -> 'QAPIDoc':
> >                          r'(Returns|Errors|Since|Notes?|Examples?|TODO):
> *',
> >                          line):
> >                      # tagged section
> > +
> > +                    if 'Note' in match.group(1):
> > +                        emsg = (
> > +                            f"The '{match.group(1)}' section is
> deprecated."
> > +                            " Please use rST's '.. note::' directive or
> "
> > +                            "another suitable admonition instead."
> > +                        )
> > +                        raise QAPIParseError(self, emsg)
>
> This isn't merely deprecated, it's a hard error.
>

Fair enuff....


> > +
> >                      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 5f03a6d733f..711a0d629c2 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 f3384e9a3bb..f179d3eff6d 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 de38a386e8f..0a294eb324e 100644
> > --- a/tests/qapi-schema/doc-good.json
> > +++ b/tests/qapi-schema/doc-good.json
> > @@ -29,7 +29,7 @@
> >  # - Second list
> >  #   Note: still in list
> >  #
> > -# Note: not in list
> > +# .. note:: not in list
> >  #
> >  # 1. Third list
> >  #    is numbered
> > @@ -155,7 +155,7 @@
> >  # @cmd-feat1: a feature
> >  # @cmd-feat2: another feature
> >  #
> > -# Note: @arg3 is undocumented
> > +# .. note:: @arg3 is undocumented
> >  #
> >  # Returns: @Object
> >  #
> > @@ -163,7 +163,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 435f6e6d768..2c9b4e419cb 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -76,7 +76,7 @@ Not in list
> >  - Second list
> >    Note: still in list
> >
> > -Note: not in list
> > +.. note:: not in list
> >
> >  1. Third list
> >     is numbered
> > @@ -169,15 +169,17 @@ description starts on the same line
> >  a feature
> >      feature=cmd-feat2
> >  another feature
> > -    section=Note
> > -@arg3 is undocumented
> > +    section=None
> > +.. note:: @arg3 is undocumented
> >      section=Returns
> >  @Object
> >      section=Errors
> >  some
> >      section=TODO
> >  frobnicate
> > -    section=Notes
> > +    section=None
> > +.. admonition:: Notes
> > +
> >   - Lorem ipsum dolor sit amet
> >   - Ut enim ad minim veniam
> >
> > diff --git a/tests/qapi-schema/doc-good.txt
> b/tests/qapi-schema/doc-good.txt
> > index 847db70412d..b89f35d5476 100644
> > --- a/tests/qapi-schema/doc-good.txt
> > +++ b/tests/qapi-schema/doc-good.txt
> > @@ -17,7 +17,9 @@ Not in list
> >
> >  * Second list Note: still in list
> >
> > -Note: not in list
> > +Note:
> > +
> > +  not in list
> >
> >  1. Third list is numbered
> >
> > @@ -193,11 +195,9 @@ Features
> >  "cmd-feat2"
> >     another feature
> >
> > +Note:
> >
> > -Note
> > -~~~~
> > -
> > -"arg3" is undocumented
> > +  "arg3" is undocumented
> >
> >
> >  Returns
> > @@ -211,9 +211,7 @@ Errors
> >
> >  some
> >
> > -
> > -Notes
> > -~~~~~
> > +Notes:
> >
> >  * Lorem ipsum dolor sit amet
> >
> > diff --git a/tests/qapi-schema/doc-interleaved-section.json
> b/tests/qapi-schema/doc-interleaved-section.json
> > index adb29e98daa..b26bc0bbb79 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.
> > +# Returns: a section.
> >  #
> >  # @foobar: catch this
> >  #
>
> I love this, and want it merged as soon as possible.  Can we spin this
> off into its own series along with its dependencies?  Feel free to throw
> in uncontroversial small fry.  Perhaps
>
>     qapi: linter fixups
>     docs/qapidoc: delint a tiny portion of the module
>     qapi/parser: preserve indentation in QAPIDoc sections
>     qapi/parser: fix comment parsing immediately following a doc block
>     docs/qapidoc: fix nested parsing under untagged sections
>     qapi: fix non-compliant JSON examples
>     qapi: ensure all errors sections are uniformly typset
>     qapi: convert "Note" sections to plain rST
>     qapi: convert "Example" sections to rST
>
> Has just one trivial conflict for me.
>

Yeah, this works ... I fixed up the prose/markup changes you pointed out
above and stuck them in separate patches. I need to go through the Examples
feedback still, but as of now:

jsnow@scv ~/s/q/qapi (sphinx-domain-prereqs-docs)> stg series --description
+ do-not-merge-add-some-ad-hoc   # [DO-NOT-MERGE]: Add some ad-hoc linting
helpers.
+ qapi-linter-fixups             # qapi: linter fixups
+ docs-qapidoc-delint-a-tiny     # docs/qapidoc: delint a tiny portion of
the module
+ qapi-parser-preserve           # qapi/parser: preserve indentation in
QAPIDoc sections
+ qapi-parser-fix-comment        # qapi/parser: fix comment parsing
immediately following a doc block
+ docs-qapidoc-fix-nested        # docs/qapidoc: fix nested parsing under
untagged sections
+ qapi-fix-non-compliant-json    # qapi: fix non-compliant JSON examples
+ qapi-ensure-all-errors         # qapi: ensure all errors sections are
uniformly typset
+ qapi-convert-note-sections-to  # qapi: convert "Note" sections to plain
rST
+ qapi-update-prose-in-note      # qapi: Update prose in Note blocks
> qapi-add-markup-to-note-blocks # qapi: Add markup to note blocks
- qapi-convert-example-sections  # qapi: convert "Example" sections to rST

Onwards to the Examples patch, ...

>

[-- Attachment #2: Type: text/html, Size: 73535 bytes --]