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,
Not mentioned, and may or may not be worth mentioning: both "Note:" and
"Notes:" become ".. note::", which renders as "Note". One instance
quoted below.
No objection to the change; you obviously double-checked it reads okay
that way.
Right, some become "Note" if it feels appropriate, while others (mentioned just below) retained their "Notes" phrasing with a custom admonition if it felt appropriate.
I can mention it more explicitly that some (but not all) "Notes" became "Note".
(I am beginning to have doubts anyone will ever read and find these detailed commits useful, but you're welcome to tell your manager how much you love my commit messages and that I deserve a raise for such heroic efforts. /s)
> 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/block-core.json b/qapi/block-core.json
> index df5e07debd2..cacedfb771c 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
[...]
> @@ -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
> ##
[...]