fridtjof/qemu-cr16
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

qapi: convert "Note" sections to plain rST

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

Convert all existing "Note" and "Notes" sections to pure rST. As part of
the conversion, capitalize the first letter of each sentence and add
trailing punctuation where appropriate to ensure notes look sensible and
consistent in rendered HTML documentation. Markup is also re-aligned to
the de-facto standard of 3 spaces for directives.

Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and
update the QAPI parser to prohibit "Note" sections while suggesting a
new syntax. The exact formatting to use is a matter of taste, but a good
candidate is simply:

.. note:: lorem ipsum ...
   ... dolor sit amet ...
   ... consectetur adipiscing elit ...

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

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

These are rendered in orange:

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

These are rendered in red:

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

These are rendered in green:

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

These are rendered in blue:

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

   admonition body text

This patch uses ".. note::" almost everywhere, with just two "caution"
directives. Several instances of "Notes:" have been converted to
merely ".. note::", or multiple ".. note::" where appropriate.
".. admonition:: notes" is used in a few places where we had an
ordered list of multiple notes that would not make sense as
standalone/separate admonitions.  Two "Note:" following "Example:"
have been turned into ordinary paragraphs within the example.

NOTE: Because qapidoc.py does not attempt to preserve source ordering of
sections, the conversion of Notes from a "tagged section" to an
"untagged section" means that rendering order for some notes *may
change* as a result of this patch. The forthcoming qapidoc.py rewrite
strictly preserves source ordering in the rendered documentation, so
this issue will be rectified in the new generator.

Signed-off-by: John Snow <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2024-06-26 18:21:16 -04:00 • committed by Markus Armbruster
parent b32a6b62a8
commit d461c27973
30 changed files with 261 additions and 253 deletions
Download patch file Download diff file Expand all files Collapse all files

28
qapi/qdev.json
View file

@ -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
#