Re: [PATCH v2 10/21] qapi: convert "Note" sections to plain rST
John Snow 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 > Acked-by: Stefan Hajnoczi [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 [...]
Re: [PATCH v2 10/21] qapi: convert "Note" sections to plain rST
On Fri, Jun 28, 2024, 5:52 AM Markus Armbruster wrote: > John Snow 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. > I meant to imply it when discussing when admonition was used, but yeah. > * 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. > Eh. we got enough commits. I think it's helpful to keep the whole conversion in one giant bang so that the diff is helpful in illustrating all of the different types of conversions. (In fact, even though I split out Example conversion for your sake in review, I think it'd be helpful to squash them together on merge for the same exact reason.) Let's just amend the commit message. > * 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? > Yep, suits me fine. > > 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 > > Acked-by: Stefan Hajnoczi [for block*.json] > > I dislike the indentation changes, and may revert them in my tree. > 😢 Would you take a patch adjusting the indent later, or will you then tell me it's not worth the git blame fuzz? :) > Reviewed-by: Markus Armbruster > >
Re: [PATCH v2 10/21] qapi: convert "Note" sections to plain rST
John Snow 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 > Acked-by: Stefan Hajnoczi [for block*.json] I dislike the indentation changes, and may revert them in my tree. Reviewed-by: Markus Armbruster
[PATCH v2 10/21] qapi: convert "Note" sections to plain rST
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 Acked-by: Stefan Hajnoczi [for block*.json] --- docs/devel/qapi-code-gen.rst | 7 +- qapi/block-core.json | 28 +++--- qapi/block.json | 2 +- qapi/char.json| 12 +-- qapi/control.json | 17 ++-- qapi/dump.json| 2 +- qapi/introspect.json | 6 +- qapi/machine-target.json | 26 +++--- qapi/machine.json | 47 +- qapi/migration.json | 12 +-- qapi/misc.json| 88 +-- qapi/net.json | 6 +- qapi/pci.json | 8 +- qapi/qdev.json| 28 +++--- qapi/qom.json | 17 ++-- qapi/rocker.json | 16 ++-- qapi/run-state.json | 18 ++-- qapi/sockets.json | 10 +-- qapi/stats.json | 22 ++--- qapi/transaction.json | 8 +- qapi/ui.json | 29 +++--- qapi/virtio.json | 12 +-- qga/qapi-schema.json | 48 +- scripts/qapi/parser.py| 15 tests/qapi-schema/doc-empty-section.err | 2 +- tests/qapi-schema/doc-empty-section.json | 2 +- tests/qapi-schema/doc-good.json | 4 +- tests/qapi-schema/doc-good.out| 8 +- tests/qapi-schema/doc-good.txt| 10 +-- .../qapi-schema/doc-interleaved-section.json | 2 +- 30 files changed, 260 insertions(+), 252 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index cee43222f19..ae97b335cbf 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -995,14 +995,13 @@ line "Features:", like this:: # @feature: Description text A tagged section begins with a paragraph that starts with one of the -following words: "Note:"/"Notes:", "Since:", "Example:"/"Examples:", -"Returns:", "Errors:", "TODO:". It ends with the start of a new -section. +following words: "Since:", "Example:"/"Examples:", "Returns:", +"Errors:", "TODO:". It ends with the start of a new section. The second and subsequent lines of tagged sections must be indented like this:: - # Note: Ut enim ad minim veniam, quis nostrud exercitation ullamco + # TODO: Ut enim ad minim veniam, quis nostrud exercitation ullamco # laboris nisi ut aliquip
