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. Markup is also re-aligned to > the de-facto standard of 3 spaces for directives. > > 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 ... > ... dolor sit amet ... > ... consectetur adipiscing elit ... > > ... 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. Several instances of "Notes:" have been converted to merely > ".. note::" where appropriate, but ".. 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. > > NOTE: Because qapidoc.py does not attempt to preserve source ordering of > sections, the conversion of Notes from a "tagged section" to an > "untagged section" means that rendering order for some notes *may > change* as a result of this patch. The forthcoming qapidoc.py rewrite > strictly preserves source ordering in the rendered documentation, so > this issue will be rectified in the new generator. > > Signed-off-by: John Snow <js...@redhat.com> > Acked-by: Stefan Hajnoczi <stefa...@redhat.com> [for block*.json]
[...] > diff --git a/qapi/migration.json b/qapi/migration.json > index 9ec9ef36c47..26ad5e5e7a3 100644 > --- a/qapi/migration.json > +++ b/qapi/migration.json > @@ -1456,8 +1456,8 @@ > # > # Cancel the current executing migration process. > # > -# Notes: This command succeeds even if there is no migration process > -# running. > +# .. note:: This command succeeds even if there is no migration process > +# running. > # > # Since: 0.14 > # > @@ -1589,16 +1589,16 @@ > # > # Since: 0.14 > # > -# Notes: > +# .. admonition:: Notes > # > # 1. The 'query-migrate' command should be used to check > # migration's progress and final result (this information is > # provided by the 'status' member) Missing period, will touch up in my tree. > # > -# 2. All boolean arguments default to false > +# 2. All boolean arguments default to false. > # > # 3. The user Monitor's "detach" argument is invalid in QMP and > -# should not be used > +# should not be used. > # > # 4. The uri argument should have the Uniform Resource Identifier > # of default destination VM. This connection will be bound to > @@ -1672,7 +1672,7 @@ > # > # Since: 2.3 > # > -# Notes: > +# .. admonition:: Notes > # > # 1. It's a bad idea to use a string for the uri, but it needs to > # stay compatible with -incoming and the format of the uri is [...]