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.
I looked for hunks that don't 1:1 replace "Note:" or "Notes:" by ".. note::." Findings: * Two hunks replace by ".. caution::" instead. Commit message got it. Good. * Four hunks replace by ".. admonition:: notes", one of them as a test. Commit message got it. Good. * Three hunks split "Notes:" into multiple ".. note::". Good, but could be mentioned in commit message. * Two hunks drop "Note:", changing it into paragraph. The paragraph merges into the preceding "Example" section. Good, but should be mentioned in the commit message, or turned into a separate patch. * One hunk adjusts a test case for the removal of the "Note:" tag. Good, but could be mentioned in the commit message. Perhaps tweak the paragraph above: This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. 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. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example. Okay? > 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] I dislike the indentation changes, and may revert them in my tree. Reviewed-by: Markus Armbruster <arm...@redhat.com>