On Fri, Jun 21, 2024 at 8:08 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/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', > > [...] > "v2" of this series now declines to move the note in this patch and instead moves it in a separate patch that also enforces source order more strictly so that the move can be explained in detail. Rendering order diverges from source order briefly as a result; I will mention that in the commit message instead. (I don't think it's easy or worth doing to re-order the patches such that source and render order never diverge; too much engineering for so temporary a minor issue. Not to mention the source and render order is already divergent in many places, so I don't think it's a regression so much as it is a temporary .... lateralgression?)
