2020-09-25 16:23:10 +00:00
|
|
|
Section
|
|
|
|
|
*******
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Subsection
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
*with emphasis* "var" {in braces}
|
|
|
|
|
|
|
|
|
|
* List item one
|
|
|
|
|
|
|
|
|
|
* Two, multiple lines
|
|
|
|
|
|
|
|
|
|
* Three Still in list
|
|
|
|
|
|
|
|
|
|
Not in list
|
|
|
|
|
|
|
|
|
|
* Second list Note: still in list
|
|
|
|
|
|
|
|
|
|
Note: not in list
|
|
|
|
|
|
|
|
|
|
1. Third list is numbered
|
|
|
|
|
|
|
|
|
|
2. another item
|
|
|
|
|
|
|
|
|
|
Returns: the King Since: the first age Notes:
|
|
|
|
|
|
|
|
|
|
1. Lorem ipsum dolor sit amet
|
|
|
|
|
|
|
|
|
|
2. Ut enim ad minim veniam
|
|
|
|
|
|
|
|
|
|
Duis aute irure dolor
|
|
|
|
|
|
|
|
|
|
Example:
|
|
|
|
|
|
|
|
|
|
-> in <- out Examples: - *verbatim* - {braces}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"Enum" (Enum)
|
|
|
|
|
-------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Values
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
2021-08-04 08:31:05 +00:00
|
|
|
"one" (**If: **"IFONE")
|
2024-02-16 14:58:25 +00:00
|
|
|
The _one_ {and only}, description on the same line
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
"two"
|
|
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"enum-feat"
|
|
|
|
|
Also _one_ {and only}
|
|
|
|
|
|
2021-10-25 04:24:02 +00:00
|
|
|
"enum-member-feat"
|
|
|
|
|
a member feature
|
|
|
|
|
|
2020-09-25 16:23:10 +00:00
|
|
|
"two" is undocumented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-04 08:31:05 +00:00
|
|
|
"IFCOND"
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
"Base" (Object)
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"base1": "Enum"
|
2024-02-16 14:58:25 +00:00
|
|
|
description starts on a new line, minimally indented
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
|
2021-08-04 08:31:01 +00:00
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-31 12:38:04 +00:00
|
|
|
"IFALL1 and IFALL2"
|
2021-08-04 08:31:01 +00:00
|
|
|
|
|
|
|
|
|
2020-09-25 16:23:10 +00:00
|
|
|
"Variant1" (Object)
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
A paragraph
|
|
|
|
|
|
2024-02-16 14:58:25 +00:00
|
|
|
Another paragraph
|
|
|
|
|
|
|
|
|
|
"var1" is undocumented
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
2021-08-04 08:31:05 +00:00
|
|
|
"var1": "string" (**If: **"IFSTR")
|
2020-09-25 16:23:10 +00:00
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"variant1-feat"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
"member-feat"
|
|
|
|
|
a member feature
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"Variant2" (Object)
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"Object" (Object)
|
|
|
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
The members of "Base"
|
|
|
|
|
The members of "Variant1" when "base1" is ""one""
|
2021-08-31 12:38:04 +00:00
|
|
|
The members of "Variant2" when "base1" is ""two"" (**If: **"IFONE or
|
|
|
|
|
IFTWO")
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"union-feat1"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"Alternate" (Alternate)
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"i": "int"
|
2024-02-16 14:58:25 +00:00
|
|
|
description starts on the same line remainder indented the same "b"
|
|
|
|
|
is undocumented
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
"b": "boolean"
|
|
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"alt-feat"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
|
2021-08-04 08:31:04 +00:00
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-31 12:38:05 +00:00
|
|
|
"not (IFONE or IFTWO)"
|
2021-08-04 08:31:04 +00:00
|
|
|
|
|
|
|
|
|
2020-09-25 16:23:10 +00:00
|
|
|
Another subsection
|
|
|
|
|
==================
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"cmd" (Command)
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"arg1": "int"
|
2024-02-16 14:58:25 +00:00
|
|
|
description starts on a new line, indented
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
"arg2": "string" (optional)
|
2024-02-16 14:58:25 +00:00
|
|
|
description starts on the same line remainder indented differently
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
"arg3": "boolean"
|
|
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"cmd-feat1"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
"cmd-feat2"
|
|
|
|
|
another feature
|
|
|
|
|
|
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::", 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.
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 <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-06-26 22:21:16 +00:00
|
|
|
Note:
|
2020-09-25 16:23:10 +00:00
|
|
|
|
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::", 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.
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 <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-06-26 22:21:16 +00:00
|
|
|
"arg3" is undocumented
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"Object"
|
|
|
|
|
|
|
|
|
|
|
2024-02-27 11:39:11 +00:00
|
|
|
Errors
|
|
|
|
|
~~~~~~
|
|
|
|
|
|
|
|
|
|
some
|
|
|
|
|
|
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::", 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.
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 <jsnow@redhat.com>
Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json]
Message-ID: <20240626222128.406106-11-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message clarified slightly, period added to one more note]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-06-26 22:21:16 +00:00
|
|
|
Notes:
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
* Lorem ipsum dolor sit amet
|
|
|
|
|
|
|
|
|
|
* Ut enim ad minim veniam
|
|
|
|
|
|
|
|
|
|
Duis aute irure dolor
|
|
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
Example: Ideal fast-food burger situation:
|
2020-09-25 16:23:10 +00:00
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
-> "in"
|
|
|
|
|
<- "out"
|
2020-09-25 16:23:10 +00:00
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
Examples:
|
2020-09-25 16:23:10 +00:00
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
- Not a QMP code block
|
|
|
|
|
- Merely a preformatted code block literal
|
|
|
|
|
It isn't even an rST list.
|
2020-09-25 16:23:10 +00:00
|
|
|
- *verbatim*
|
|
|
|
|
- {braces}
|
|
|
|
|
|
2024-06-26 22:21:19 +00:00
|
|
|
Note::
|
|
|
|
|
Ceci n'est pas une note
|
|
|
|
|
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
Since
|
|
|
|
|
~~~~~
|
|
|
|
|
|
|
|
|
|
2.10
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"cmd-boxed" (Command)
|
|
|
|
|
---------------------
|
|
|
|
|
|
|
|
|
|
If you're bored enough to read this, go see a video of boxed cats
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
The members of "Object"
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"cmd-feat1"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
"cmd-feat2"
|
|
|
|
|
another feature
|
|
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
Example::
|
2020-09-25 16:23:10 +00:00
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
-> "this example"
|
2020-09-25 16:23:10 +00:00
|
|
|
|
qapi: remove "Example" doc section
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c279737), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
2024-07-17 02:13:11 +00:00
|
|
|
<- "has no title"
|
2020-09-25 16:23:10 +00:00
|
|
|
|
|
|
|
|
|
2021-03-23 09:40:10 +00:00
|
|
|
"EVT_BOXED" (Event)
|
2020-09-25 16:23:10 +00:00
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
The members of "Object"
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"feat3"
|
|
|
|
|
a feature
|