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, 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/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'] } [...]