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

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@redhat.com> writes:
>
>> 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.

[...]

> So you're right, "kind of both": they work just fine with the new doc
> generator, except for the "====" rST headings, because the parser still
> recognizes them as old-style schema doc headings.
>
>> 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.
>
> Yes, please.
>
> [...]

I'm going with

    docs/sphinx: remove special parsing for freeform sections

    Remove the QAPI doc section heading syntax, use plain rST section
    headings instead.

    Tests and documentation are updated to match.

    Interestingly, Plain rST headings work fine before this patch, except
    for over- and underlining with '=', which the doc parser rejected as
    invalid QAPI doc section heading in free-form comments.