[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend
[PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions
Mon, 10 Aug 2020 20:50:14 +0100
Update the documentation of QAPI document comment syntax to match
the new rST backend requirements. The principal changes are:
* whitespace is now significant, and multiline definitions
must have their second and subsequent lines indented to
match the first line
* general rST format markup is permitted, not just the small
set of markup the old texinfo generator handled. For most
things (notably bulleted and itemized lists) the old format
is the same as rST was.
* Specific things that might trip people up:
- instead of *bold* and _italic_ rST has **bold** and *italic*
- lists need a preceding and following blank line
- a lone literal '*' will need to be backslash-escaped to
avoid a rST syntax error
* the old leading '|' for example (literal text) blocks is
replaced by the standard rST '::' literal block.
* headings and subheadings must now be in a freeform
documentation comment of their own
* we support arbitrary levels of sub- and sub-sub-heading, not
just a main and sub-heading like the old texinfo generator
Reviewed-by: Richard Henderson <email@example.com>
Signed-off-by: Peter Maydell <firstname.lastname@example.org>
docs/devel/qapi-code-gen.txt | 90 ++++++++++++++++++++++++------------
1 file changed, 61 insertions(+), 29 deletions(-)
diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
index 69eede6c283..263f1c0b44c 100644
@@ -824,21 +824,39 @@ See below for more on definition documentation.
Free-form documentation may be used to provide additional text and
+==== Headings and subheadings ====
+A free-form documentation comment containing a single line
+which starts with some '=' symbols and then a space defines
+a section heading:
+ # = This is a top level heading
+ # This is a free-form comment which will go under the
+ # top level heading.
+ # == This is a second level heading
+Section headings must always be correctly nested, so you can only
+define a third-level heading inside a second-level heading, and so
+on. The documentation generator will catch nesting mistakes and report
+a syntax error.
==== Documentation markup ====
-Comment text starting with '=' is a section title:
+Documentation comments can use most rST markup. In particular,
+a '::' literal block can be used for examples:
- # = Section title
-Double the '=' for a subsection title:
- # == Subsection title
-'|' denotes examples:
- # | Text of the example, may span
- # | multiple lines
+ # ::
+ # Text of the example, may span
+ # multiple lines
'*' starts an itemized list:
@@ -854,37 +872,35 @@ A decimal number followed by '.' starts a numbered list:
# multiple lines
# 2. Second item
-The actual number doesn't matter. You could even use '*' instead of
-'2.' for the second item.
+The actual number doesn't matter.
-Lists can't be nested. Blank lines are currently not supported within
+Lists of either kind must be preceded and followed by a blank line.
+If a list item's text spans multiple lines, then the second and
+subsequent lines must be correctly indented to line up with the
+first character of the first line.
-Additional whitespace between the initial '#' and the comment text is
-*foo* and _foo_ are for strong and emphasis styles respectively (they
-do not work over multiple lines). @foo is used to reference a name in
+The usual '**strong**', '*emphasised*' and '``literal``' markup should
+be used. If you need a single literal '*' you will need to backslash-escape it.
+As an extension beyond the usual rST syntax, you can also
+use '@foo' to reference a name in the schema; this is rendered
+the same way as '``foo``'.
-# = Section
-# == Subsection
-# Some text foo with *strong* and _emphasis_
+# Some text foo with **bol** and *emphasis*
# 1. with a list
# 2. like that
# And some code:
-# | $ echo foo
-# | -> do this
-# | <- get that
+# $ echo foo
+# -> do this
+# <- get that
==== Definition documentation ====
Definition documentation, if present, must immediately precede the
@@ -899,6 +915,12 @@ commands and events), member (for structs and unions),
alternates), or value (for enums), and finally optional tagged
+Descriptions of arguments can span multiple lines; if they
+do then the second and subsequent lines must be indented
+to line up with the first character of the first line of the
+description. The parser will report a syntax error if there
+is insufficient indentation.
FIXME: the parser accepts these things in almost any order.
FIXME: union branches should be described, too.
@@ -912,6 +934,16 @@ The section ends with the start of a new section.
A 'Since: x.y.z' tagged section lists the release that introduced the
+The text of a section can start on a new line, in
+which case it must not be indented at all. It can also start
+on the same line as the 'Note:', 'Returns:', etc tag. In this
+case if it spans multiple lines then second and subsequent
+lines must be indented to match the first.
+An 'Example' or 'Examples' section is automatically rendered
+entirely as literal fixed-width text. In other sections,
+the text is formatted, and rST markup can be used.
- [PATCH v5 05/20] qapi/machine.json: Escape a literal '*' in doc comment, (continued)
- [PATCH v5 05/20] qapi/machine.json: Escape a literal '*' in doc comment, Peter Maydell, 2020/08/10
- [PATCH v5 06/20] tests/qapi/doc-good.json: Prepare for qapi-doc Sphinx extension, Peter Maydell, 2020/08/10
- [PATCH v5 07/20] scripts/qapi: Move doc-comment whitespace stripping to doc.py, Peter Maydell, 2020/08/10
- [PATCH v5 08/20] scripts/qapi/parser.py: improve doc comment indent handling, Peter Maydell, 2020/08/10
- [PATCH v5 10/20] docs/interop: Convert qemu-ga-ref to rST, Peter Maydell, 2020/08/10
- [PATCH v5 09/20] docs/sphinx: Add new qapi-doc Sphinx extension, Peter Maydell, 2020/08/10
- [PATCH v5 11/20] docs/interop: Convert qemu-qmp-ref to rST, Peter Maydell, 2020/08/10
- [PATCH v5 12/20] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/08/10
- [PATCH v5 13/20] qga/qapi-schema.json: Add some headings, Peter Maydell, 2020/08/10
- [PATCH v5 15/20] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions,
Peter Maydell <=
- [PATCH v5 14/20] scripts/qapi: Remove texinfo generation support, Peter Maydell, 2020/08/10
- [PATCH v5 16/20] Makefile: Remove redundant Texinfo related rules, Peter Maydell, 2020/08/10
- [PATCH v5 18/20] Remove Texinfo related files from .gitignore and git.orderfile, Peter Maydell, 2020/08/10
- [PATCH v5 17/20] scripts/texi2pod: Delete unused script, Peter Maydell, 2020/08/10
- [PATCH v5 19/20] configure: Drop texinfo requirement, Peter Maydell, 2020/08/10
- [PATCH v5 20/20] Remove texinfo dependency from docker and CI configs, Peter Maydell, 2020/08/10
- Re: [PATCH v5 00/20] Convert QAPI doc comments to generate rST instead of texinfo, Peter Maydell, 2020/08/27