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

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3458 bytes --]

On Fri, Jun 27, 2025, 5:52 AM Markus Armbruster <armbru@redhat.com> wrote:

> 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?
>

Ehm... Kind of both? I guess I hadn't considered that rST headings might
already work without the switch. I guess they didn't because of the
headerless freeform section bug I fix in this series.

I guess you're technically right, I just never thought of it in that way.

I'll update the message so I don't confuse you in the future.

>
> > 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
>
> [...]
>
>

[-- Attachment #2: Type: text/html, Size: 4805 bytes --]