[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: |
Peter Maydell |
Subject: |
Re: [PATCH v6 17/21] docs/devel/qapi-code-gen.txt: Update to new rST backend conventions |
Date: |
Tue, 29 Sep 2020 13:43:14 +0100 |
On Tue, 29 Sep 2020 at 13:35, Markus Armbruster <armbru@redhat.com> wrote:
>
> 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"?
Yes :-)
> 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?
I moved the first sentence to patch 5 in v6 (ie to the patch
which updates parser.py to enforce those indentation restrictions),
so as to make patches 1..5 suitable for merging even if we needed
to respin the second half of the series.
> > @@ -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.
I also moved this paragraph into patch 5 (where it appears just
above the "A 'Since:..." text you can see in the context here)
but forgot to delete the copy of it here, so at this point it is
duplicate text and should not be in this patch. Oops.
> > +
> > +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.
(This patch is the right place for this paragraph.)
thanks
-- PMM
- Re: [PATCH v6 14/21] meson.build: Make manuals depend on source to Sphinx extensions, (continued)
- [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
- [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
- Re: [PATCH v6 00/21] Convert QAPI doc comments to generate rST instead of texinfo, John Snow, 2020/09/25