Re: [PATCH v2 2/3] docs: remove legacy QAPI manual generator

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Mon, Jun 16, 2025 at 8:20 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > Thanks for your service!
>> >
>> > Remove the old qapidoc and the option to enable the transmogrifier,
>> > leaving the "transmogrifier" as the ONLY qapi doc generator. This in
>> > effect also converts the QAPI test to use the new documentation
>> > generator, too.
>> >
>> > Signed-off-by: John Snow <jsnow@redhat.com>
>>
>> Fails "make check", because tests/qapi-schema/doc-good.txt needs an
>> update.
>>
>> Unfortunately, the diff of the update is less than useful.  To make
>> sense of what changes, I split doc-good.txt into parts before and after,
>> and diffed those.
>>
>>
>>   diff -rupw o/01 n/01
>>   --- o/01      2025-06-16 13:53:05.036940854 +0200
>>   +++ n/01      2025-06-16 13:49:07.167435996 +0200
>>   @@ -1,11 +1,13 @@
>>    Section
>>    *******
>>
>>   +Just text, no heading.
>>   +
>>
>> Looks like a bug fix.  Needs a mention in the commit message then.
>>
>
> I think before, these sections just got ... discarded?

Looks like it.  Definitely a bug.

>                                                        but with no special
> formatting, they just get copied through. You could call it a bugfix, you
> could call it an unintentional side effect.

I'm calling it a bug fix.  Where was it broken?  Dig, dig, dig, ...

commit b61a4eb3f32ce74c5ffe001806f9e786788a546f
Author: John Snow <jsnow@redhat.com>
Date:   Sun Feb 23 22:37:35 2025 -0500

    docs/qapidoc: support header-less freeform sections
    
    The code as written crashes when a free-form documentation block doesn't
    start with a heading or subheading, for example:
    
    | ##
    | # Just text, no heading.
    | ##
    
    The code will attempt to use the `node` variable uninitialized. To fix,
    create a generic block to insert the doc text into.
    
    (This patch also removes a lingering pylint warning in the QAPIDoc
    implementation that prevents getting a clean baseline to use for
    forthcoming additions.)
    
    Fixes: 43e0d14ee09a (docs/sphinx: fix extra stuff in TOC after freeform QMP sections)
    Signed-off-by: John Snow <jsnow@redhat.com>
    Message-ID: <20250224033741.222749-5-jsnow@redhat.com>
    Reviewed-by: Markus Armbruster <armbru@redhat.com>
    [Test updated to cover this]
    Signed-off-by: Markus Armbruster <armbru@redhat.com>

The patch adds such a block to doc-good.json.  It shows up in expected
output doc-good.out, but not in doc-good.txt.  Review fail.

Please mention the fix in the commit message, and add the Fixes: tag.

[...]