Re: [PATCH 05/11] docs/qapi-code-gen: add "Details" docs subsection

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Mostly, this is just adding a heading and explaining that arbitrary
> rST formatting is allowed in this section.
>
> Note: The QAPI parser still refers to these sections internally as
> "PLAIN",

Really?

>          but I wanted to name this documentation section after the
> eventual, true name for the section. It is effectively only an
> implementation detail at this point.
>
> Signed-off-by: John Snow <jsnow@redhat.com>
> ---
>  docs/devel/qapi-code-gen.rst | 11 +++++++++--
>  1 file changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index fcb52ce157e..8fc75488019 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -1035,8 +1035,15 @@ detailing a relevant error condition.  For example::
>   #     - Any other error returns a GenericError.
>  
>  
> -In other sections, the text is formatted, and rST markup can be
> -used.
> +Details
> +^^^^^^^
> +
> +Details sections are comprised of one or more paragraphs of rST
> +formatted text, but otherwise are not marked up with any QAPI-specific
> +syntax.

Feels awkward.  You're trying to define you're talking about, but what
you're talking about is distinguished by absence of syntax, which makes
it harder to nail down.

I can't see how to do this better right now.  I'll come back to it.

>          In general, this text contains in-depth explanations of the
> +definition being documented and may include various rST admonitions
> +like ``.. seealso::``, ``.. note::``, etc. This is also the section
> +where QMP usage examples should be placed.
>  
>  QMP Examples can be added by using the ``.. qmp-example::`` directive.
>  In its simplest form, this can be used to contain a single QMP code