[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST bac
From: |
Markus Armbruster |
Subject: |
Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions |
Date: |
Tue, 29 Sep 2020 14:35:39 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/27.1 (gnu/linux) |
Peter Maydell <peter.maydell@linaro.org> writes:
> Update the documentation of QAPI document comment syntax to match
> the new rST backend requirements. The principal changes are:
> * whitespace is now significant,
Well, differently significant :) Anyway, close enough.
> 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.
"was the same as rST is"?
> * 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.
> * we support arbitrary levels of sub- and sub-sub-heading, not
> just a main and sub-heading like the old texinfo generator
Possibly noteworthy: lists can now be nested. Can add that in my tree.
>
> Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
> docs/devel/qapi-code-gen.txt | 83 +++++++++++++++++++++++-------------
> 1 file changed, 53 insertions(+), 30 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.txt b/docs/devel/qapi-code-gen.txt
> index 69eaffac376..7d2479dde82 100644
> --- a/docs/devel/qapi-code-gen.txt
> +++ b/docs/devel/qapi-code-gen.txt
> @@ -824,23 +824,37 @@ See below for more on definition documentation.
> Free-form documentation may be used to provide additional text and
> structuring content.
>
> +==== Headings and subheadings ====
> +
> +A free-form documentation comment containing a 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
> + ##
> +
> +A heading line must be the first line of the documentation
> +comment block.
> +
> +Section headings must always be correctly nested, so you can only
> +define a third-level heading inside a second-level heading, and so on.
>
> ==== 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
> -
> -Both are only permitted in free-form documentation.
> -
> -'|' denotes examples:
> -
> - # | Text of the example, may span
> - # | multiple lines
> + # ::
> + #
> + # Text of the example, may span
> + # multiple lines
>
> '*' starts an itemized list:
>
> @@ -856,34 +870,33 @@ 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.
> +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
> -permitted.
> -
> -*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 schema.
> +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``'.
>
> Example:
>
> ##
> -# = Section
> -# == Subsection
> -#
> -# Some text foo with *strong* and _emphasis_
> +# Some text foo with **bold** and *emphasis*
> # 1. with a list
> # 2. like that
> #
> # And some code:
> -# | $ echo foo
> -# | -> do this
> -# | <- get that
> #
> +# ::
> +#
> +# $ echo foo
> +# -> do this
> +# <- get that
> ##
>
>
v5 had
@@ -899,6 +915,12 @@ commands and events), member (for structs and unions),
branch (for
alternates), or value (for enums), and finally optional tagged
sections.
+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.
I questioned the value of the last sentence. You dropped both.
Intentional?
> @@ -937,6 +950,16 @@ multiline argument descriptions.
> A 'Since: x.y.z' tagged section lists the release that introduced the
> definition.
>
> +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.
> +
> For example:
>
> ##
- [PATCH v6 14/21] meson.build: Make manuals depend on source to Sphinx extensions, (continued)
- [PATCH v6 14/21] meson.build: Make manuals depend on source to Sphinx extensions, Peter Maydell, 2020/09/25
- [PATCH v6 10/21] qapi: Use rST markup for literal blocks, Peter Maydell, 2020/09/25
- [PATCH v6 20/21] configure: Drop texinfo requirement, Peter Maydell, 2020/09/25
- [PATCH v6 12/21] tests/qapi-schema: Convert doc-good.json to rST-style strong/emphasis, Peter Maydell, 2020/09/25
- [PATCH v6 13/21] meson.build: Move SPHINX_ARGS to top level meson.build file, Peter Maydell, 2020/09/25
- [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions, Peter Maydell, 2020/09/25
- Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions,
Markus Armbruster <=
- [PATCH v6 16/21] scripts/qapi: Remove texinfo generation support, Peter Maydell, 2020/09/25
- [PATCH v6 18/21] scripts/texi2pod: Delete unused script, Peter Maydell, 2020/09/25
- [PATCH v6 19/21] Remove Texinfo related line from git.orderfile, Peter Maydell, 2020/09/25
- [PATCH v6 21/21] Remove texinfo dependency from docker and CI configs, Peter Maydell, 2020/09/25