John Snow <js...@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. > 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 <js...@redhat.com> > Acked-by: Stefan Hajnoczi <stefa...@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 > ## [...]
