mirror of
https://github.com/xemu-project/xemu.git
synced 2025-04-02 11:11:48 -04:00
d461c27973
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>
283 lines
2.7 KiB
Text
283 lines
2.7 KiB
Text
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
|
|
~~~~~~
|
|
|
|
"one" (**If: **"IFONE")
|
|
The _one_ {and only}, description on the same line
|
|
|
|
"two"
|
|
Not documented
|
|
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
"enum-feat"
|
|
Also _one_ {and only}
|
|
|
|
"enum-member-feat"
|
|
a member feature
|
|
|
|
"two" is undocumented
|
|
|
|
|
|
If
|
|
~~
|
|
|
|
"IFCOND"
|
|
|
|
|
|
"Base" (Object)
|
|
---------------
|
|
|
|
|
|
Members
|
|
~~~~~~~
|
|
|
|
"base1": "Enum"
|
|
description starts on a new line, minimally indented
|
|
|
|
|
|
If
|
|
~~
|
|
|
|
"IFALL1 and IFALL2"
|
|
|
|
|
|
"Variant1" (Object)
|
|
-------------------
|
|
|
|
A paragraph
|
|
|
|
Another paragraph
|
|
|
|
"var1" is undocumented
|
|
|
|
|
|
Members
|
|
~~~~~~~
|
|
|
|
"var1": "string" (**If: **"IFSTR")
|
|
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""
|
|
The members of "Variant2" when "base1" is ""two"" (**If: **"IFONE or
|
|
IFTWO")
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
"union-feat1"
|
|
a feature
|
|
|
|
|
|
"Alternate" (Alternate)
|
|
-----------------------
|
|
|
|
|
|
Members
|
|
~~~~~~~
|
|
|
|
"i": "int"
|
|
description starts on the same line remainder indented the same "b"
|
|
is undocumented
|
|
|
|
"b": "boolean"
|
|
Not documented
|
|
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
"alt-feat"
|
|
a feature
|
|
|
|
|
|
If
|
|
~~
|
|
|
|
"not (IFONE or IFTWO)"
|
|
|
|
|
|
Another subsection
|
|
==================
|
|
|
|
|
|
"cmd" (Command)
|
|
---------------
|
|
|
|
|
|
Arguments
|
|
~~~~~~~~~
|
|
|
|
"arg1": "int"
|
|
description starts on a new line, indented
|
|
|
|
"arg2": "string" (optional)
|
|
description starts on the same line remainder indented differently
|
|
|
|
"arg3": "boolean"
|
|
Not documented
|
|
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
"cmd-feat1"
|
|
a feature
|
|
|
|
"cmd-feat2"
|
|
another feature
|
|
|
|
Note:
|
|
|
|
"arg3" is undocumented
|
|
|
|
|
|
Returns
|
|
~~~~~~~
|
|
|
|
"Object"
|
|
|
|
|
|
Errors
|
|
~~~~~~
|
|
|
|
some
|
|
|
|
Notes:
|
|
|
|
* Lorem ipsum dolor sit amet
|
|
|
|
* Ut enim ad minim veniam
|
|
|
|
Duis aute irure dolor
|
|
|
|
|
|
Example
|
|
~~~~~~~
|
|
|
|
-> in
|
|
<- out
|
|
|
|
|
|
Examples
|
|
~~~~~~~~
|
|
|
|
- *verbatim*
|
|
- {braces}
|
|
|
|
|
|
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
|
|
|
|
|
|
"EVT_BOXED" (Event)
|
|
-------------------
|
|
|
|
|
|
Arguments
|
|
~~~~~~~~~
|
|
|
|
The members of "Object"
|
|
|
|
Features
|
|
~~~~~~~~
|
|
|
|
"feat3"
|
|
a feature
|