Re: [PATCH 19/20] qapi: convert "Note" sections to plain rST
John Snow writes: > On Fri, Jun 14, 2024, 9:44 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. >> > >> > Update the QAPI parser to now prohibit special "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. >> > > Store this paragraph in your L1 cache for a moment ... > >> >> > 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 ".. notes::" almost everywhere, with just two "caution" >> > directives. ".. admonition:: notes" is used in a few places where we had >> > an ordered list of multiple notes. >> > >> > Signed-off-by: John Snow >> > --- >> > qapi/block-core.json | 30 +++ >> > qapi/block.json | 2 +- >> > qapi/char.json| 12 +-- >> > qapi/control.json | 15 ++-- >> > 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 | 7 +- >> > qapi/qdev.json| 30 +++ >> > qapi/qom.json | 19 ++-- >> > 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| 9 ++ >> > tests/qapi-schema/doc-empty-section.err | 2 +- >> > tests/qapi-schema/doc-empty-section.json | 2 +- >> > tests/qapi-schema/doc-good.json | 6 +- >> > tests/qapi-schema/doc-good.out| 10 ++- >> > tests/qapi-schema/doc-good.txt| 14 ++- >> > .../qapi-schema/doc-interleaved-section.json | 2 +- >> > 29 files changed, 258 insertions(+), 252 deletions(-) >> >> Missing: update of docs/devel/qapi-code-gen.rst. Something like >> >> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst >> index f453bd3546..1a4e240adb 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 ex ea commodo consequat. >> # >> # Duis aute irure dolor in reprehenderit in voluptate velit esse >> >> > Done. Thanks! >> > >> > diff --git a/qapi/block-core.json b/qapi/block-core.json >> > index 64fe5240cc9..530af40404d 100644 >> > --- a/qapi/block-core.json >> > +++ b/qapi/block-core.json >> > @@ -1510,7 +1510,7 @@ >> > # @mode: whether and how QEMU should create a new image, default is >> > # 'absolute-paths'. >> > # >> > -# Note: Either @device or @node-name must be set but not both. >> > +# .. note:: Either @device or @node-name must be set but not both.
Re: [PATCH 19/20] qapi: convert "Note" sections to plain rST
On Fri, Jun 14, 2024, 9:44 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. > > > > Update the QAPI parser to now prohibit special "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. > Store this paragraph in your L1 cache for a moment ... > > > 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 ".. notes::" almost everywhere, with just two "caution" > > directives. ".. admonition:: notes" is used in a few places where we had > > an ordered list of multiple notes. > > > > Signed-off-by: John Snow > > --- > > qapi/block-core.json | 30 +++ > > qapi/block.json | 2 +- > > qapi/char.json| 12 +-- > > qapi/control.json | 15 ++-- > > 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 | 7 +- > > qapi/qdev.json| 30 +++ > > qapi/qom.json | 19 ++-- > > 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| 9 ++ > > tests/qapi-schema/doc-empty-section.err | 2 +- > > tests/qapi-schema/doc-empty-section.json | 2 +- > > tests/qapi-schema/doc-good.json | 6 +- > > tests/qapi-schema/doc-good.out| 10 ++- > > tests/qapi-schema/doc-good.txt| 14 ++- > > .../qapi-schema/doc-interleaved-section.json | 2 +- > > 29 files changed, 258 insertions(+), 252 deletions(-) > > Missing: update of docs/devel/qapi-code-gen.rst. Something like > > diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst > index f453bd3546..1a4e240adb 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 ex ea commodo consequat. > # > # Duis aute irure dolor in reprehenderit in voluptate velit esse > > Done. > > > > diff --git a/qapi/block-core.json b/qapi/block-core.json > > index 64fe5240cc9..530af40404d 100644 > > --- a/qapi/block-core.json > > +++ b/qapi/block-core.json > > @@ -1510,7 +1510,7 @@ > > # @mode: whether and how QEMU should create a new image, default is > > # 'absolute-paths'. > > # > > -# Note: Either @device or @node-name must be set but not both. > > +# .. note:: Either @device or @node-name must be set but not both. > > The commit message talks about ".. Note::", but you actually use > ".. note::". Is there a difference? > Retrieve paragraph from L1 cache. Nope! Sp
Re: [PATCH 19/20] 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.
>
> Update the QAPI parser to now prohibit special "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.
>
> 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 ".. notes::" almost everywhere, with just two "caution"
> directives. ".. admonition:: notes" is used in a few places where we had
> an ordered list of multiple notes.
>
> Signed-off-by: John Snow
> ---
> qapi/block-core.json | 30 +++
> qapi/block.json | 2 +-
> qapi/char.json| 12 +--
> qapi/control.json | 15 ++--
> 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 | 7 +-
> qapi/qdev.json| 30 +++
> qapi/qom.json | 19 ++--
> 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| 9 ++
> tests/qapi-schema/doc-empty-section.err | 2 +-
> tests/qapi-schema/doc-empty-section.json | 2 +-
> tests/qapi-schema/doc-good.json | 6 +-
> tests/qapi-schema/doc-good.out| 10 ++-
> tests/qapi-schema/doc-good.txt| 14 ++-
> .../qapi-schema/doc-interleaved-section.json | 2 +-
> 29 files changed, 258 insertions(+), 252 deletions(-)
Missing: update of docs/devel/qapi-code-gen.rst. Something like
diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
index f453bd3546..1a4e240adb 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 ex ea commodo consequat.
#
# Duis aute irure dolor in reprehenderit in voluptate velit esse
>
> diff --git a/qapi/block-core.json b/qapi/block-core.json
> index 64fe5240cc9..530af40404d 100644
> --- a/qapi/block-core.json
> +++ b/qapi/block-core.json
> @@ -1510,7 +1510,7 @@
> # @mode: whether and how QEMU should create a new image, default is
> # 'absolute-paths'.
> #
> -# Note: Either @device or @node-name must be set but not both.
> +# .. note:: Either @device or @node-name must be set but not both.
The commit message talks about ".. Note::", but you actually use
".. note::". Is there a difference?
> #
> ##
> { 'struct': 'BlockdevSnapshotSync',
> @@ -1616,9 +1616,9 @@
> #
> # @unstable: Member @x-perf is experimental.
> #
> -# Note: @on-source-error and @on-target-error only affect background
> -# I/O. If an error occurs during a guest write request, the
> -# device's rerror/werror actions will be used.
> +# .. note:: @on-source-error and @on-target-error only affect backg
[PATCH 19/20] 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.
Update the QAPI parser to now prohibit special "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.
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 ".. notes::" almost everywhere, with just two "caution"
directives. ".. admonition:: notes" is used in a few places where we had
an ordered list of multiple notes.
Signed-off-by: John Snow
---
qapi/block-core.json | 30 +++
qapi/block.json | 2 +-
qapi/char.json| 12 +--
qapi/control.json | 15 ++--
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 | 7 +-
qapi/qdev.json| 30 +++
qapi/qom.json | 19 ++--
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| 9 ++
tests/qapi-schema/doc-empty-section.err | 2 +-
tests/qapi-schema/doc-empty-section.json | 2 +-
tests/qapi-schema/doc-good.json | 6 +-
tests/qapi-schema/doc-good.out| 10 ++-
tests/qapi-schema/doc-good.txt| 14 ++-
.../qapi-schema/doc-interleaved-section.json | 2 +-
29 files changed, 258 insertions(+), 252 deletions(-)
diff --git a/qapi/block-core.json b/qapi/block-core.json
index 64fe5240cc9..530af40404d 100644
--- a/qapi/block-core.json
+++ b/qapi/block-core.json
@@ -1510,7 +1510,7 @@
# @mode: whether and how QEMU should create a new image, default is
# 'absolute-paths'.
#
-# Note: Either @device or @node-name must be set but not both.
+# .. note:: Either @device or @node-name must be set but not both.
#
##
{ 'struct': 'BlockdevSnapshotSync',
@@ -1616,9 +1616,9 @@
#
# @unstable: Member @x-perf is experimental.
#
-# Note: @on-source-error and @on-target-error only affect background
-# I/O. If an error occurs during a guest write request, the
-# device's rerror/werror actions will be used.
+# .. note:: @on-source-error and @on-target-error only affect background
+#I/O. If an error occurs during a guest write request, the device's
+#rerror/werror actions will be used.
#
# Since: 4.2
##
@@ -5534,8 +5534,8 @@
# after this event and must be repaired (Since 2.2; before, every
# BLOCK_IMAGE_CORRUPTED event was fatal)
#
-# Note: If action is "stop", a STOP event will eventually follow the
-# BLOCK_IO_ERROR event.
+# .. note:: If action is "stop", a STOP event will eventually follow the
+#BLOCK_IO_ERROR event.
#
# Example:
#
@@ -5581,8 +5581,8 @@
# field is a debugging aid for humans, it should not be parsed by
# applications) (since: 2.2)
#
-# Note: If action is "stop", a STOP event will eventually follow the
-# BLOCK_IO_ERROR event
+# .. note:: If action is "stop", a STOP event will eventually follow the
+#BLOCK_IO_ERROR event.
#
# Since: 0.13
#
@@ -5720,8 +5720,8 @@
#
# @speed: rate limit, bytes per second
#
-# Note: The "ready to complete" status is always reset by a
-# @BLOCK_JOB_ERROR event
+# .. note:: The "ready to complete" status is always reset by a
+#@BLOCK_JOB_ERROR event.
#
# Since: 1.3
#
@@ -5974,7 +5974,7 @@
#
# @sectors-count: failed read operation sector count
#
-# Note: This event is rate-limited.
+# .. note:: This event is rate-limited.
#
# Since: 2.0
#
@@ -6005,7 +6005,7 @@
#
# @
