On Wed, Jun 19, 2024, 9:07 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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'] } > > [...] > Apologies, I meant to do this but forgot there were two cases and only nabbed one. Fixing. >
