Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
John Snow writes: > On Fri, Jun 21, 2024 at 8:23 AM Markus Armbruster wrote: [...] >> My reason for four spaces is reducing churn. To see by how much, I >> redid your change. I found a few more notes that don't start with a >> capital letter, or don't end with a period. >> > > ^ Guess I'll re-audit for v2. Hang on to the list of cases you found. Happy to share my patch. > (Sorry for the churn, though. I obviously don't mind it as much as you do, > but I suspect I'm a lot less nimble with fiddling through git history than > you are and find the value of avoiding churn to be ... lower than you do, > in general. Respecting reviewer time is a strong argument, I apologize that > some non-mechanical changes snuck into the patch. The downside of hacking > together a very large series.) You did a good job splitting it up. Minor mistakes are bound to happen. Got to give the reviewer soemthing to find ;) [...]
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Fri, Jun 21, 2024 at 8:23 AM Markus Armbruster wrote: > John Snow writes: > > > On Thu, Jun 20, 2024 at 11:46 AM John Snow wrote: > > > >> > >> > >> On Thu, Jun 20, 2024, 9:35 AM Markus Armbruster > wrote: > >> > >>> Markus Armbruster writes: > >>> > >>> > John Snow writes: > >>> > >>> [...] > >>> > >>> >> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json > >>> >> index b3de1fb6b3a..57598331c5c 100644 > >>> >> --- a/qga/qapi-schema.json > >>> >> +++ b/qga/qapi-schema.json > >>> > >>> [...] > >>> > >>> >> @@ -631,8 +632,8 @@ > >>> >> # Errors: > >>> >> # - If hybrid suspend is not supported, Unsupported > >>> >> # > >>> >> -# Notes: It's strongly recommended to issue the guest-sync command > >>> >> -# before sending commands when the guest resumes > >>> >> +# .. note:: It's strongly recommended to issue the guest-sync > command > >>> >> +#before sending commands when the guest resumes. > >>> >> # > >>> >> # Since: 1.1 > >>> >> ## > >>> >> @@ -1461,16 +1462,15 @@ > >>> >> # * POSIX: as defined by os-release(5) > >>> >> # * Windows: contains string "server" or "client" > >>> >> # > >>> >> -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > >>> >> -# @version, @version-id, @variant and @variant-id follow the > >>> >> -# definition specified in os-release(5). Refer to the manual > page > >>> >> -# for exact description of the fields. Their values are taken > >>> >> -# from the os-release file. If the file is not present in the > >>> >> -# system, or the values are not present in the file, the fields > >>> >> -# are not included. > >>> >> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > >>> >> +#@version, @version-id, @variant and @variant-id follow the > >>> >> +#definition specified in os-release(5). Refer to the manual > page > >>> for > >>> >> +#exact description of the fields. Their values are taken from > the > >>> >> +#os-release file. If the file is not present in the system, or > >>> the > >>> >> +#values are not present in the file, the fields are not > included. > >>> >> # > >>> >> -# On Windows the values are filled from information gathered > from > >>> >> -# the system. > >>> >> +#On Windows the values are filled from information gathered > from > >>> >> +#the system. > >>> > > >>> > Please don't change the indentation here. I get the same output with > >>> > > >>> > @@ -1461,7 +1462,7 @@ > >>> ># * POSIX: as defined by os-release(5) > >>> ># * Windows: contains string "server" or "client" > >>> ># > >>> > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > >>> > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > >>> ># @version, @version-id, @variant and @variant-id follow the > >>> ># definition specified in os-release(5). Refer to the manual > page > >>> ># for exact description of the fields. Their values are taken > >>> > >>> I'm blind. Actually, you change indentation of subsequent lines from 4 > >>> to 3 *everywhere*. I guess you do that to make subsequent lines line > up > >>> with the directive, here "note". > >>> > >>> Everywhere else, we indent such lines by 4. Hmm. How terrible would > it > >>> be not to mess with the alignment? > >>> > >>> If we want to use 3 for directives, is it worth pointing out in the > >>> commit message? > >>> > >>> [...] > >>> > >> > >> Let me look up some conventions and see what's the most prominent... as > >> well as testing what emacs does by default (or if emacs can be > configured > >> to do what we want with in-tree style config. Warning: I am functionally > >> inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on > your > >> own. I'm sorry.) > >> > >> I use three myself by force of habit and have some mild reluctance to > >> respin for that reason, but ... guess we ought to be consistent if we > can. > >> > >> (No idea where my habit came from. Maybe it is just because it looks > nice > >> to me and no other reason.) > >> > >> ((I have no plans, nor desire, to write any kind of checker to enforce > >> this, though - sorry.)) > >> > > > > Sphinx doc uses three spaces: > > > https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives > > > > ... but it warns that it's arbitrary; but it seems common to align with > the > > directive. > > > > * > > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes > >footnotes require "at least 3" spaces > > > > * > > > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives > > directives are only required to be "indented" but the amount isn't > > specified. rst docs use three. > > > > I'm happy with three; I don't believe we need to make it consistent with > > e.g. our home-spun field list syntax (arguments, features) or with code > > blocks. I think whatever looks good in the source is fine, and I
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Fri, Jun 21, 2024 at 8:08 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.
> >
> > 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
> > Acked-by: Stefan Hajnoczi [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?)
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
John Snow writes: > On Thu, Jun 20, 2024 at 11:46 AM John Snow wrote: > >> >> >> On Thu, Jun 20, 2024, 9:35 AM Markus Armbruster wrote: >> >>> Markus Armbruster writes: >>> >>> > John Snow writes: >>> >>> [...] >>> >>> >> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json >>> >> index b3de1fb6b3a..57598331c5c 100644 >>> >> --- a/qga/qapi-schema.json >>> >> +++ b/qga/qapi-schema.json >>> >>> [...] >>> >>> >> @@ -631,8 +632,8 @@ >>> >> # Errors: >>> >> # - If hybrid suspend is not supported, Unsupported >>> >> # >>> >> -# Notes: It's strongly recommended to issue the guest-sync command >>> >> -# before sending commands when the guest resumes >>> >> +# .. note:: It's strongly recommended to issue the guest-sync command >>> >> +#before sending commands when the guest resumes. >>> >> # >>> >> # Since: 1.1 >>> >> ## >>> >> @@ -1461,16 +1462,15 @@ >>> >> # * POSIX: as defined by os-release(5) >>> >> # * Windows: contains string "server" or "client" >>> >> # >>> >> -# Notes: On POSIX systems the fields @id, @name, @pretty-name, >>> >> -# @version, @version-id, @variant and @variant-id follow the >>> >> -# definition specified in os-release(5). Refer to the manual page >>> >> -# for exact description of the fields. Their values are taken >>> >> -# from the os-release file. If the file is not present in the >>> >> -# system, or the values are not present in the file, the fields >>> >> -# are not included. >>> >> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, >>> >> +#@version, @version-id, @variant and @variant-id follow the >>> >> +#definition specified in os-release(5). Refer to the manual page >>> for >>> >> +#exact description of the fields. Their values are taken from the >>> >> +#os-release file. If the file is not present in the system, or >>> the >>> >> +#values are not present in the file, the fields are not included. >>> >> # >>> >> -# On Windows the values are filled from information gathered from >>> >> -# the system. >>> >> +#On Windows the values are filled from information gathered from >>> >> +#the system. >>> > >>> > Please don't change the indentation here. I get the same output with >>> > >>> > @@ -1461,7 +1462,7 @@ >>> ># * POSIX: as defined by os-release(5) >>> ># * Windows: contains string "server" or "client" >>> ># >>> > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, >>> > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, >>> ># @version, @version-id, @variant and @variant-id follow the >>> ># definition specified in os-release(5). Refer to the manual page >>> ># for exact description of the fields. Their values are taken >>> >>> I'm blind. Actually, you change indentation of subsequent lines from 4 >>> to 3 *everywhere*. I guess you do that to make subsequent lines line up >>> with the directive, here "note". >>> >>> Everywhere else, we indent such lines by 4. Hmm. How terrible would it >>> be not to mess with the alignment? >>> >>> If we want to use 3 for directives, is it worth pointing out in the >>> commit message? >>> >>> [...] >>> >> >> Let me look up some conventions and see what's the most prominent... as >> well as testing what emacs does by default (or if emacs can be configured >> to do what we want with in-tree style config. Warning: I am functionally >> inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your >> own. I'm sorry.) >> >> I use three myself by force of habit and have some mild reluctance to >> respin for that reason, but ... guess we ought to be consistent if we can. >> >> (No idea where my habit came from. Maybe it is just because it looks nice >> to me and no other reason.) >> >> ((I have no plans, nor desire, to write any kind of checker to enforce >> this, though - sorry.)) >> > > Sphinx doc uses three spaces: > https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives > > ... but it warns that it's arbitrary; but it seems common to align with the > directive. > > * > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes >footnotes require "at least 3" spaces > > * > https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives > directives are only required to be "indented" but the amount isn't > specified. rst docs use three. > > I'm happy with three; I don't believe we need to make it consistent with > e.g. our home-spun field list syntax (arguments, features) or with code > blocks. I think whatever looks good in the source is fine, and I think > three looks good for directives. I don't think we need to require this, but > I can mention in the commit message that I chose it for the sake of > aesthetics and for parity with what most rST docs appear to use. My reason for four spaces is reducing churn. To see by how much, I redid your change. I found a few more
Re: [PATCH 09/13] 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.
>
> 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
> Acked-by: Stefan Hajnoczi [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',
[...]
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
John Snow writes: > On Wed, Jun 19, 2024, 8:49 AM Markus Armbruster wrote: > >> John Snow writes: [...] >> > diff --git a/tests/qapi-schema/doc-interleaved-section.json >> > b/tests/qapi-schema/doc-interleaved-section.json >> > index adb29e98daa..b26bc0bbb79 100644 >> > --- a/tests/qapi-schema/doc-interleaved-section.json >> > +++ b/tests/qapi-schema/doc-interleaved-section.json >> > @@ -10,7 +10,7 @@ >> > # >> > # bao >> > # >> > -# Note: a section. >> > +# Returns: a section. >> > # >> > # @foobar: catch this >> > # >> >> "Returns:" is only valid for commands, and this is a struct. Let's use >> "TODO:" instead. >> > > Weird that it didn't prohibit it. Bug? No: it simply chokes on "description of '@foobar:' follows a section" before it can choke on "'Returns' section is only valid for commands".
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
John Snow writes: > Apologies, I meant to do this but forgot there were two cases and only > nabbed one. > > Fixing. No problem at all!
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Thu, Jun 20, 2024 at 11:46 AM John Snow wrote: > > > On Thu, Jun 20, 2024, 9:35 AM Markus Armbruster wrote: > >> Markus Armbruster writes: >> >> > John Snow writes: >> >> [...] >> >> >> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json >> >> index b3de1fb6b3a..57598331c5c 100644 >> >> --- a/qga/qapi-schema.json >> >> +++ b/qga/qapi-schema.json >> >> [...] >> >> >> @@ -631,8 +632,8 @@ >> >> # Errors: >> >> # - If hybrid suspend is not supported, Unsupported >> >> # >> >> -# Notes: It's strongly recommended to issue the guest-sync command >> >> -# before sending commands when the guest resumes >> >> +# .. note:: It's strongly recommended to issue the guest-sync command >> >> +#before sending commands when the guest resumes. >> >> # >> >> # Since: 1.1 >> >> ## >> >> @@ -1461,16 +1462,15 @@ >> >> # * POSIX: as defined by os-release(5) >> >> # * Windows: contains string "server" or "client" >> >> # >> >> -# Notes: On POSIX systems the fields @id, @name, @pretty-name, >> >> -# @version, @version-id, @variant and @variant-id follow the >> >> -# definition specified in os-release(5). Refer to the manual page >> >> -# for exact description of the fields. Their values are taken >> >> -# from the os-release file. If the file is not present in the >> >> -# system, or the values are not present in the file, the fields >> >> -# are not included. >> >> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, >> >> +#@version, @version-id, @variant and @variant-id follow the >> >> +#definition specified in os-release(5). Refer to the manual page >> for >> >> +#exact description of the fields. Their values are taken from the >> >> +#os-release file. If the file is not present in the system, or >> the >> >> +#values are not present in the file, the fields are not included. >> >> # >> >> -# On Windows the values are filled from information gathered from >> >> -# the system. >> >> +#On Windows the values are filled from information gathered from >> >> +#the system. >> > >> > Please don't change the indentation here. I get the same output with >> > >> > @@ -1461,7 +1462,7 @@ >> ># * POSIX: as defined by os-release(5) >> ># * Windows: contains string "server" or "client" >> ># >> > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, >> > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, >> ># @version, @version-id, @variant and @variant-id follow the >> ># definition specified in os-release(5). Refer to the manual page >> ># for exact description of the fields. Their values are taken >> >> I'm blind. Actually, you change indentation of subsequent lines from 4 >> to 3 *everywhere*. I guess you do that to make subsequent lines line up >> with the directive, here "note". >> >> Everywhere else, we indent such lines by 4. Hmm. How terrible would it >> be not to mess with the alignment? >> >> If we want to use 3 for directives, is it worth pointing out in the >> commit message? >> >> [...] >> > > Let me look up some conventions and see what's the most prominent... as > well as testing what emacs does by default (or if emacs can be configured > to do what we want with in-tree style config. Warning: I am functionally > inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your > own. I'm sorry.) > > I use three myself by force of habit and have some mild reluctance to > respin for that reason, but ... guess we ought to be consistent if we can. > > (No idea where my habit came from. Maybe it is just because it looks nice > to me and no other reason.) > > ((I have no plans, nor desire, to write any kind of checker to enforce > this, though - sorry.)) > Sphinx doc uses three spaces: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives ... but it warns that it's arbitrary; but it seems common to align with the directive. * https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#footnotes footnotes require "at least 3" spaces * https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#directives directives are only required to be "indented" but the amount isn't specified. rst docs use three. I'm happy with three; I don't believe we need to make it consistent with e.g. our home-spun field list syntax (arguments, features) or with code blocks. I think whatever looks good in the source is fine, and I think three looks good for directives. I don't think we need to require this, but I can mention in the commit message that I chose it for the sake of aesthetics and for parity with what most rST docs appear to use. Note: emacs behavior for wrapping paragraphs in our QAPI files does not create an indent if there isn't already one. I think convincing emacs to apply rST rules inside of a JSON file we lie and call a Python file might be beyond my ability to do quickly. The d
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Thu, Jun 20, 2024, 9:55 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. > > > > 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, > > Not mentioned, and may or may not be worth mentioning: both "Note:" and > "Notes:" become ".. note::", which renders as "Note". One instance > quoted below. > > No objection to the change; you obviously double-checked it reads okay > that way. > Right, some become "Note" if it feels appropriate, while others (mentioned just below) retained their "Notes" phrasing with a custom admonition if it felt appropriate. I can mention it more explicitly that some (but not all) "Notes" became "Note". (I am beginning to have doubts anyone will ever read and find these detailed commits useful, but you're welcome to tell your manager how much you love my commit messages and that I deserve a raise for such heroic efforts. /s) > >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 > > Acked-by: Stefan Hajnoczi [for block*.json] > > [...] > > > diff --git a/qapi/block-core.json b/qapi/block-core.json > > index df5e07debd2..cacedfb771c 100644 > > --- a/qapi/block-core.json > > +++ b/qapi/block-core.json > > [...] > > > @@ -6048,9 +6048,9 @@ > > # > > # @name: the name of the internal snapshot to be created > > # > > -# Notes: In transaction, if @name is empty, or any snapshot matching > > -# @name exists, the operation will fail. Only some image formats > > -# support it, for example, qcow2, and rbd. > > +# .. note:: In transaction, if @name is empty, or any snapshot matching > > +#@name exists, the operation will fail. Only some image formats > > +#support it, for example, qcow2, and rbd. > > # > > # Since: 1.7 > > ## > > [...] > >
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Thu, Jun 20, 2024, 9:35 AM Markus Armbruster wrote: > Markus Armbruster writes: > > > John Snow writes: > > [...] > > >> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json > >> index b3de1fb6b3a..57598331c5c 100644 > >> --- a/qga/qapi-schema.json > >> +++ b/qga/qapi-schema.json > > [...] > > >> @@ -631,8 +632,8 @@ > >> # Errors: > >> # - If hybrid suspend is not supported, Unsupported > >> # > >> -# Notes: It's strongly recommended to issue the guest-sync command > >> -# before sending commands when the guest resumes > >> +# .. note:: It's strongly recommended to issue the guest-sync command > >> +#before sending commands when the guest resumes. > >> # > >> # Since: 1.1 > >> ## > >> @@ -1461,16 +1462,15 @@ > >> # * POSIX: as defined by os-release(5) > >> # * Windows: contains string "server" or "client" > >> # > >> -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > >> -# @version, @version-id, @variant and @variant-id follow the > >> -# definition specified in os-release(5). Refer to the manual page > >> -# for exact description of the fields. Their values are taken > >> -# from the os-release file. If the file is not present in the > >> -# system, or the values are not present in the file, the fields > >> -# are not included. > >> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > >> +#@version, @version-id, @variant and @variant-id follow the > >> +#definition specified in os-release(5). Refer to the manual page > for > >> +#exact description of the fields. Their values are taken from the > >> +#os-release file. If the file is not present in the system, or the > >> +#values are not present in the file, the fields are not included. > >> # > >> -# On Windows the values are filled from information gathered from > >> -# the system. > >> +#On Windows the values are filled from information gathered from > >> +#the system. > > > > Please don't change the indentation here. I get the same output with > > > > @@ -1461,7 +1462,7 @@ > ># * POSIX: as defined by os-release(5) > ># * Windows: contains string "server" or "client" > ># > > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, > ># @version, @version-id, @variant and @variant-id follow the > ># definition specified in os-release(5). Refer to the manual page > ># for exact description of the fields. Their values are taken > > I'm blind. Actually, you change indentation of subsequent lines from 4 > to 3 *everywhere*. I guess you do that to make subsequent lines line up > with the directive, here "note". > > Everywhere else, we indent such lines by 4. Hmm. How terrible would it > be not to mess with the alignment? > > If we want to use 3 for directives, is it worth pointing out in the > commit message? > > [...] > Let me look up some conventions and see what's the most prominent... as well as testing what emacs does by default (or if emacs can be configured to do what we want with in-tree style config. Warning: I am functionally inept at emacs lisp. Warning 2x: [neo]vi[m] users, you're entirely on your own. I'm sorry.) I use three myself by force of habit and have some mild reluctance to respin for that reason, but ... guess we ought to be consistent if we can. (No idea where my habit came from. Maybe it is just because it looks nice to me and no other reason.) ((I have no plans, nor desire, to write any kind of checker to enforce this, though - sorry.))
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Wed, Jun 19, 2024, 9:07 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.
> >
> > 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
> > Acked-by: Stefan Hajnoczi [for block*.json]
>
> [...]
>
> > diff --git a/qapi/control.json b/qapi/control.json
> > index 10c906fa0e7..59d5e00c151 100644
> > --- a/qapi/control.json
> > +++ b/qapi/control.json
> > @@ -22,14 +22,13 @@
> > # "arguments": { "enable": [ "oob" ] } }
> > # <- { "return": {} }
> > #
> > -# Notes: This command is valid exactly when first connecting: it must
> > -# be issued before any other command will be accepted, and will
> > -# fail once the monitor is accepting other commands. (see qemu
> > -# docs/interop/qmp-spec.rst)
> > +# .. note:: This command is valid exactly when first connecting: it must
> > +#be issued before any other command will be accepted, and will fail
> > +#once the monitor is accepting other commands. (see qemu
> > +#docs/interop/qmp-spec.rst)
> > #
> > -# The QMP client needs to explicitly enable QMP capabilities,
> > -# otherwise all the QMP capabilities will be turned off by
> > -# default.
> > +# .. note:: The QMP client needs to explicitly enable QMP capabilities,
> > +#otherwise all the QMP capabilities will be turned off by default.
> > #
> > # Since: 0.13
> > ##
> > @@ -150,8 +149,8 @@
> > # ]
> > #}
> > #
> > -# Note: This example has been shortened as the real response is too
> > -# long.
> > +# This example has been shortened as the real response is too long.
> > +#
>
> Here's one way to transform the elision note, ...
>
> > ##
> > { 'command': 'query-commands', 'returns': ['CommandInfo'],
> >'allow-preconfig': true }
>
> [...]
>
> > diff --git a/qapi/pci.json b/qapi/pci.json
> > index 08bf6958634..f51159a2c4c 100644
> > --- a/qapi/pci.json
> > +++ b/qapi/pci.json
> > @@ -146,8 +146,8 @@
> > #
> > # @regions: a list of the PCI I/O regions associated with the device
> > #
> > -# Notes: the contents of @class_info.desc are not stable and should
> > -# only be treated as informational.
> > +# .. note:: The contents of @class_info.desc are not stable and should
> > +#only be treated as informational.
> > #
> > # Since: 0.14
> > ##
> > @@ -311,7 +311,8 @@
> > # ]
> > #}
> > #
> > -# Note: This example has been shortened as the real response is too
> > +# Note: This example has been shortened as the real response is too
> > # long.
> > +#
>
> ... and here's another way. Same way would be better, wouldn't it?
> They actually are after PATCH 13:
>
> -# Note: This example has been shortened as the real response is too
> -# long.
> +# This example has been shortened as the real response is too long.
>
> Move that hunk here, please.
>
> > ##
> > { 'command': 'query-pci', 'returns': ['PciInfo'] }
>
> [...]
>
Apologies, I meant to do this but forgot there were two cases and only
nabbed one.
Fixing.
>
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
On Wed, Jun 19, 2024, 8:49 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.
> >
> > Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...
> >
> > ... Update the QAPI parser to prohibit "Note" sections while suggesting
>
> Scratch "... ..." and downcase "Update"?
>
> > 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
> > Acked-by: Stefan Hajnoczi [for block*.json]
>
> [...]
>
> > diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> > index b3de1fb6b3a..57598331c5c 100644
> > --- a/qga/qapi-schema.json
> > +++ b/qga/qapi-schema.json
> > @@ -422,8 +422,9 @@
> > # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
> > # below)
> > #
> > -# Note: This may fail to properly report the current state as a result
> > -# of some other guest processes having issued an fs freeze/thaw.
> > +# .. note:: This may fail to properly report the current state as a
> > +#result of some other guest processes having issued an fs
> > +#freeze/thaw.
> > #
> > # Since: 0.15.0
> > ##
> > @@ -443,9 +444,9 @@
> > #
> > # Returns: Number of file systems currently frozen.
> > #
> > -# Note: On Windows, the command is implemented with the help of a
> > -# Volume Shadow-copy Service DLL helper. The frozen state is
> > -# limited for up to 10 seconds by VSS.
> > +# .. note:: On Windows, the command is implemented with the help of a
> > +#Volume Shadow-copy Service DLL helper. The frozen state is limited
> > +#for up to 10 seconds by VSS.
> > #
> > # Since: 0.15.0
> > ##
> > @@ -479,10 +480,10 @@
> > #
> > # Returns: Number of file systems thawed by this call
> > #
> > -# Note: if return value does not match the previous call to
> > -# guest-fsfreeze-freeze, this likely means some freezable
> > -# filesystems were unfrozen before this call, and that the
> > -# filesystem state may have changed before issuing this command.
> > +# .. note:: If return value does not match the previous call to
> > +#guest-fsfreeze-freeze, this likely means some freezable filesystems
> > +#were unfrozen before this call, and that the filesystem state may
> > +#have changed before issuing this command.
> > #
> > # Since: 0.15.0
> > ##
> > @@ -560,8 +561,8 @@
> > # Errors:
> > # - If suspend to disk is not supported, Unsupported
> > #
> > -# Notes: It's strongly recommended to issue the guest-sync command
> > -# before sending commands when the guest resumes
> > +# .. note:: It's strongly recommended to issue the guest-sync command
> > +#before sending commands when the guest resumes.
> > #
> > # Since: 1.1
> > ##
> > @@ -596,8 +597,8 @@
> > # Errors:
> > # - If suspend to ram is not supported, Unsupported
> > #
> > -# Notes: It's strongly recommended to issue the guest-sync command
> > -# before sending commands when the guest resumes
> > +# .. note:: It's strongly recommended to issue the guest-sync command
> > +#before sending commands when the guest resumes.
> > #
> > # Since: 1.1
> > ##
> > @@ -631,8 +632,8 @@
> > # Errors:
> > # - If hybrid suspend is not supported, Unsupported
> > #
> > -# Notes: It's strongly recommended to issue the guest-sync command
> > -# before sending commands when the guest resumes
> > +# .. note:: It's strongly recommend
Re: [PATCH 09/13] 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. > > 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, Not mentioned, and may or may not be worth mentioning: both "Note:" and "Notes:" become ".. note::", which renders as "Note". One instance quoted below. No objection to the change; you obviously double-checked it reads okay that way. >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 > Acked-by: Stefan Hajnoczi [for block*.json] [...] > diff --git a/qapi/block-core.json b/qapi/block-core.json > index df5e07debd2..cacedfb771c 100644 > --- a/qapi/block-core.json > +++ b/qapi/block-core.json [...] > @@ -6048,9 +6048,9 @@ > # > # @name: the name of the internal snapshot to be created > # > -# Notes: In transaction, if @name is empty, or any snapshot matching > -# @name exists, the operation will fail. Only some image formats > -# support it, for example, qcow2, and rbd. > +# .. note:: In transaction, if @name is empty, or any snapshot matching > +#@name exists, the operation will fail. Only some image formats > +#support it, for example, qcow2, and rbd. > # > # Since: 1.7 > ## [...]
Re: [PATCH 09/13] qapi: convert "Note" sections to plain rST
Markus Armbruster writes: > John Snow writes: [...] >> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json >> index b3de1fb6b3a..57598331c5c 100644 >> --- a/qga/qapi-schema.json >> +++ b/qga/qapi-schema.json [...] >> @@ -631,8 +632,8 @@ >> # Errors: >> # - If hybrid suspend is not supported, Unsupported >> # >> -# Notes: It's strongly recommended to issue the guest-sync command >> -# before sending commands when the guest resumes >> +# .. note:: It's strongly recommended to issue the guest-sync command >> +#before sending commands when the guest resumes. >> # >> # Since: 1.1 >> ## >> @@ -1461,16 +1462,15 @@ >> # * POSIX: as defined by os-release(5) >> # * Windows: contains string "server" or "client" >> # >> -# Notes: On POSIX systems the fields @id, @name, @pretty-name, >> -# @version, @version-id, @variant and @variant-id follow the >> -# definition specified in os-release(5). Refer to the manual page >> -# for exact description of the fields. Their values are taken >> -# from the os-release file. If the file is not present in the >> -# system, or the values are not present in the file, the fields >> -# are not included. >> +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, >> +#@version, @version-id, @variant and @variant-id follow the >> +#definition specified in os-release(5). Refer to the manual page for >> +#exact description of the fields. Their values are taken from the >> +#os-release file. If the file is not present in the system, or the >> +#values are not present in the file, the fields are not included. >> # >> -# On Windows the values are filled from information gathered from >> -# the system. >> +#On Windows the values are filled from information gathered from >> +#the system. > > Please don't change the indentation here. I get the same output with > > @@ -1461,7 +1462,7 @@ ># * POSIX: as defined by os-release(5) ># * Windows: contains string "server" or "client" ># > -# Notes: On POSIX systems the fields @id, @name, @pretty-name, > +# .. note:: On POSIX systems the fields @id, @name, @pretty-name, ># @version, @version-id, @variant and @variant-id follow the ># definition specified in os-release(5). Refer to the manual page ># for exact description of the fields. Their values are taken I'm blind. Actually, you change indentation of subsequent lines from 4 to 3 *everywhere*. I guess you do that to make subsequent lines line up with the directive, here "note". Everywhere else, we indent such lines by 4. Hmm. How terrible would it be not to mess with the alignment? If we want to use 3 for directives, is it worth pointing out in the commit message? [...]
Re: [PATCH 09/13] 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.
>
> 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
> Acked-by: Stefan Hajnoczi [for block*.json]
[...]
> diff --git a/qapi/control.json b/qapi/control.json
> index 10c906fa0e7..59d5e00c151 100644
> --- a/qapi/control.json
> +++ b/qapi/control.json
> @@ -22,14 +22,13 @@
> # "arguments": { "enable": [ "oob" ] } }
> # <- { "return": {} }
> #
> -# Notes: This command is valid exactly when first connecting: it must
> -# be issued before any other command will be accepted, and will
> -# fail once the monitor is accepting other commands. (see qemu
> -# docs/interop/qmp-spec.rst)
> +# .. note:: This command is valid exactly when first connecting: it must
> +#be issued before any other command will be accepted, and will fail
> +#once the monitor is accepting other commands. (see qemu
> +#docs/interop/qmp-spec.rst)
> #
> -# The QMP client needs to explicitly enable QMP capabilities,
> -# otherwise all the QMP capabilities will be turned off by
> -# default.
> +# .. note:: The QMP client needs to explicitly enable QMP capabilities,
> +#otherwise all the QMP capabilities will be turned off by default.
> #
> # Since: 0.13
> ##
> @@ -150,8 +149,8 @@
> # ]
> #}
> #
> -# Note: This example has been shortened as the real response is too
> -# long.
> +# This example has been shortened as the real response is too long.
> +#
Here's one way to transform the elision note, ...
> ##
> { 'command': 'query-commands', 'returns': ['CommandInfo'],
>'allow-preconfig': true }
[...]
> diff --git a/qapi/pci.json b/qapi/pci.json
> index 08bf6958634..f51159a2c4c 100644
> --- a/qapi/pci.json
> +++ b/qapi/pci.json
> @@ -146,8 +146,8 @@
> #
> # @regions: a list of the PCI I/O regions associated with the device
> #
> -# Notes: the contents of @class_info.desc are not stable and should
> -# only be treated as informational.
> +# .. note:: The contents of @class_info.desc are not stable and should
> +#only be treated as informational.
> #
> # Since: 0.14
> ##
> @@ -311,7 +311,8 @@
> # ]
> #}
> #
> -# Note: This example has been shortened as the real response is too
> +# Note: This example has been shortened as the real response is too
> # long.
> +#
... and here's another way. Same way would be better, wouldn't it?
They actually are after PATCH 13:
-# Note: This example has been shortened as the real response is too
-# long.
+# This example has been shortened as the real response is too long.
Move that hunk here, please.
> ##
> { 'command': 'query-pci', 'returns': ['PciInfo'] }
[...]
Re: [PATCH 09/13] 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.
>
> Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and ...
>
> ... Update the QAPI parser to prohibit "Note" sections while suggesting
Scratch "... ..." and downcase "Update"?
> 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
> Acked-by: Stefan Hajnoczi [for block*.json]
[...]
> diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json
> index b3de1fb6b3a..57598331c5c 100644
> --- a/qga/qapi-schema.json
> +++ b/qga/qapi-schema.json
> @@ -422,8 +422,9 @@
> # Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined
> # below)
> #
> -# Note: This may fail to properly report the current state as a result
> -# of some other guest processes having issued an fs freeze/thaw.
> +# .. note:: This may fail to properly report the current state as a
> +#result of some other guest processes having issued an fs
> +#freeze/thaw.
> #
> # Since: 0.15.0
> ##
> @@ -443,9 +444,9 @@
> #
> # Returns: Number of file systems currently frozen.
> #
> -# Note: On Windows, the command is implemented with the help of a
> -# Volume Shadow-copy Service DLL helper. The frozen state is
> -# limited for up to 10 seconds by VSS.
> +# .. note:: On Windows, the command is implemented with the help of a
> +#Volume Shadow-copy Service DLL helper. The frozen state is limited
> +#for up to 10 seconds by VSS.
> #
> # Since: 0.15.0
> ##
> @@ -479,10 +480,10 @@
> #
> # Returns: Number of file systems thawed by this call
> #
> -# Note: if return value does not match the previous call to
> -# guest-fsfreeze-freeze, this likely means some freezable
> -# filesystems were unfrozen before this call, and that the
> -# filesystem state may have changed before issuing this command.
> +# .. note:: If return value does not match the previous call to
> +#guest-fsfreeze-freeze, this likely means some freezable filesystems
> +#were unfrozen before this call, and that the filesystem state may
> +#have changed before issuing this command.
> #
> # Since: 0.15.0
> ##
> @@ -560,8 +561,8 @@
> # Errors:
> # - If suspend to disk is not supported, Unsupported
> #
> -# Notes: It's strongly recommended to issue the guest-sync command
> -# before sending commands when the guest resumes
> +# .. note:: It's strongly recommended to issue the guest-sync command
> +#before sending commands when the guest resumes.
> #
> # Since: 1.1
> ##
> @@ -596,8 +597,8 @@
> # Errors:
> # - If suspend to ram is not supported, Unsupported
> #
> -# Notes: It's strongly recommended to issue the guest-sync command
> -# before sending commands when the guest resumes
> +# .. note:: It's strongly recommended to issue the guest-sync command
> +#before sending commands when the guest resumes.
> #
> # Since: 1.1
> ##
> @@ -631,8 +632,8 @@
> # Errors:
> # - If hybrid suspend is not supported, Unsupported
> #
> -# Notes: It's strongly recommended to issue the guest-sync command
> -# before sending commands when the guest resumes
> +# .. note:: It's strongly recommended to issue the guest-sync command
> +#before sending commands when the guest resumes.
> #
> # Since: 1.1
> ##
> @@ -1461,16 +1462,15 @@
> # * POSIX: as defined by os-release(5)
> # * Windows: contains string "server" or "client"
> #
> -# Notes: On POSIX systems the fields @id, @name, @pretty-name,
> -# @ve
[PATCH 09/13] 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. 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 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 | 7 +- qapi/qdev.json| 28 +++--- 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| 15 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 +- 30 files changed, 266 insertions(+), 255 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 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 df5e07debd2..cacedfb771c 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1619,9 +1619,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 g
