Markus Armbruster <arm...@redhat.com> writes:
> John Snow <js...@redhat.com> writes:
>
>> On Fri, Jun 27, 2025, 5:52 AM Markus Armbruster <arm...@redhat.com> wrote:
>>
>>> John Snow <js...@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.
