Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST

[Markus Armbruster]

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.
>
> 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.
>
> 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 ...
>
> ... 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. ".. 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.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]

[...]

> diff --git a/qapi/control.json b/qapi/control.json
> index 10c906fa0e7..59d5e00c151 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.
> +#

Here's one way to transform the elision note, ...

>  ##
>  { 'command': 'query-commands', 'returns': ['CommandInfo'],
>    'allow-preconfig': true }

[...]

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

... and here's another way.  Same way would be better, wouldn't it?
They actually are after PATCH 13:

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

Move that hunk here, please.

>  ##
>  { 'command': 'query-pci', 'returns': ['PciInfo'] }

[...]