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/qom.json b/qapi/qom.json > index 8bd299265e3..5bfa0ded42c 100644 > --- a/qapi/qom.json > +++ b/qapi/qom.json > @@ -195,12 +195,12 @@ > # > # @typename: the type name of an object > # > -# Note: objects can create properties at runtime, for example to > -# describe links between different devices and/or objects. These > -# properties are not included in the output of this command. > -# > # Returns: a list of ObjectPropertyInfo describing object properties > # > +# .. note:: Objects can create properties at runtime, for example to > +# describe links between different devices and/or objects. These > +# properties are not included in the output of this command. > +# > # Since: 2.12 > ## You move the note. Commit message doesn't tell why. > { 'command': 'qom-list-properties', [...]