Re: [PATCH v3 4/5] docs/sphinx: remove special parsing for freeform sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> This change removes special parsing for freeform sections and allows
> them to simply be unmodified rST syntax. The existing headings in the
> QAPI schema are adjusted to reflect the new paradigm.

"Allows them to" suggests the patch enables use of rST headings.  Is
this the case?  Or do they just work, and this patch just switches
schema code to use them, and drops now unnecessary generator code?
>
> Tests and documentation are updated to match.
>
> Signed-off-by: John Snow <jsnow@redhat.com>

[...]

> diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst
> index 231cc0fecf7..dfdbeac5a5a 100644
> --- a/docs/devel/qapi-code-gen.rst
> +++ b/docs/devel/qapi-code-gen.rst
> @@ -876,25 +876,35 @@ structuring content.
   Documentation comments
   ----------------------

   A multi-line comment that starts and ends with a ``##`` line is a
   documentation comment.

   If the documentation comment starts like ::

       ##
       # @SYMBOL:

   it documents the definition of SYMBOL, else it's free-form
   documentation.

   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::
> +Free-form documentation does not start with ``@SYMBOL`` and can contain
> +arbitrary rST markup. Headings can be marked up using the standard rST
> +syntax::

Nothing stops you from using such markup in definition documentation.
It's probably a bad idea, though.

I think it's easiest not to talk about the two kinds of doc blocks here
at all.  Scratch the first sentence?

>  
>      ##
> -    # = This is a top level heading
> +    # *************************
> +    # This is a level 2 heading
> +    # *************************
>      #
>      # This is a free-form comment which will go under the
>      # top level heading.
>      ##
>  
>      ##
> -    # == This is a second level heading
> +    # This is a third level heading
> +    # ==============================
> +    #
> +    # Level 4
> +    # _______
> +    #
> +    # Level 5
> +    # ^^^^^^^
> +    #
> +    # Level 6
> +    # """""""
>      ##
>  
> -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.
> +Level 1 headings are reserved for use by the generated documentation
> +page itself, leaving level 2 as the highest level that should be used.
>  
>  
>  Documentation markup

[...]