2020-09-25 19:23:10 +03: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 11:31:05 +03:00
|
|
|
"one" (**If: **"IFONE")
|
2024-02-16 17:58:25 +03:00
|
|
|
The _one_ {and only}, description on the same line
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
"two"
|
|
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"enum-feat"
|
|
|
|
|
Also _one_ {and only}
|
|
|
|
|
|
2021-10-25 07:24:02 +03:00
|
|
|
"enum-member-feat"
|
|
|
|
|
a member feature
|
|
|
|
|
|
2020-09-25 19:23:10 +03:00
|
|
|
"two" is undocumented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-04 11:31:05 +03:00
|
|
|
"IFCOND"
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
|
|
|
|
|
"Base" (Object)
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"base1": "Enum"
|
2024-02-16 17:58:25 +03:00
|
|
|
description starts on a new line, minimally indented
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
|
2021-08-04 11:31:01 +03:00
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-31 15:38:04 +03:00
|
|
|
"IFALL1 and IFALL2"
|
2021-08-04 11:31:01 +03:00
|
|
|
|
|
|
|
|
|
2020-09-25 19:23:10 +03:00
|
|
|
"Variant1" (Object)
|
|
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
A paragraph
|
|
|
|
|
|
2024-02-16 17:58:25 +03:00
|
|
|
Another paragraph
|
|
|
|
|
|
|
|
|
|
"var1" is undocumented
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
2021-08-04 11:31:05 +03:00
|
|
|
"var1": "string" (**If: **"IFSTR")
|
2020-09-25 19:23:10 +03: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 15:38:04 +03:00
|
|
|
The members of "Variant2" when "base1" is ""two"" (**If: **"IFONE or
|
|
|
|
|
IFTWO")
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"union-feat1"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"Alternate" (Alternate)
|
|
|
|
|
-----------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Members
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"i": "int"
|
2024-02-16 17:58:25 +03:00
|
|
|
description starts on the same line remainder indented the same "b"
|
|
|
|
|
is undocumented
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
"b": "boolean"
|
|
|
|
|
Not documented
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"alt-feat"
|
|
|
|
|
a feature
|
|
|
|
|
|
|
|
|
|
|
2021-08-04 11:31:04 +03:00
|
|
|
If
|
|
|
|
|
~~
|
|
|
|
|
|
2021-08-31 15:38:05 +03:00
|
|
|
"not (IFONE or IFTWO)"
|
2021-08-04 11:31:04 +03:00
|
|
|
|
|
|
|
|
|
2020-09-25 19:23:10 +03:00
|
|
|
Another subsection
|
|
|
|
|
==================
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
"cmd" (Command)
|
|
|
|
|
---------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"arg1": "int"
|
2024-02-16 17:58:25 +03:00
|
|
|
description starts on a new line, indented
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
"arg2": "string" (optional)
|
2024-02-16 17:58:25 +03:00
|
|
|
description starts on the same line remainder indented differently
|
2020-09-25 19:23:10 +03: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-27 01:21:16 +03:00
|
|
|
Note:
|
2020-09-25 19:23:10 +03: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-27 01:21:16 +03:00
|
|
|
"arg3" is undocumented
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
|
|
|
|
|
Returns
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
"Object"
|
|
|
|
|
|
|
|
|
|
|
2024-02-27 14:39:11 +03: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-27 01:21:16 +03:00
|
|
|
Notes:
|
2020-09-25 19:23:10 +03:00
|
|
|
|
|
|
|
|
* Lorem ipsum dolor sit amet
|
|
|
|
|
|
|
|
|
|
* Ut enim ad minim veniam
|
|
|
|
|
|
|
|
|
|
Duis aute irure dolor
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
-> in
|
|
|
|
|
<- out
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Examples
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
- *verbatim*
|
|
|
|
|
- {braces}
|
|
|
|
|
|
2024-06-27 01:21:19 +03:00
|
|
|
Note::
|
|
|
|
|
Ceci n'est pas une note
|
|
|
|
|
|
2020-09-25 19:23:10 +03: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
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Example
|
|
|
|
|
~~~~~~~
|
|
|
|
|
|
|
|
|
|
-> in
|
|
|
|
|
|
|
|
|
|
<- out
|
|
|
|
|
|
|
|
|
|
|
2021-03-23 12:40:10 +03:00
|
|
|
"EVT_BOXED" (Event)
|
2020-09-25 19:23:10 +03:00
|
|
|
-------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Arguments
|
|
|
|
|
~~~~~~~~~
|
|
|
|
|
|
|
|
|
|
The members of "Object"
|
|
|
|
|
|
|
|
|
|
Features
|
|
|
|
|
~~~~~~~~
|
|
|
|
|
|
|
|
|
|
"feat3"
|
|
|
|
|
a feature
|