Re: [PATCH 01/23] docs/qapidoc: support header-less freeform sections

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> On Mon, Dec 16, 2024 at 8:15 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > The code as written can't handle if a header isn't found, because `node`
>> > will be uninitialized.
>>
>> Yes, we initialize @node only if we have a heading.
>>
>> Made me wonder what happens when we don't.  So I deleted the = from the
>> "# = Subsection" line in doc-good.json, and got:
>>
>>     Exception occurred:
>>       File "/work/armbru/qemu/docs/sphinx/qapidoc.py", line 425, in
>> freeform
>>         self._parse_text_into_node(text, node)
>>                                          ^^^^
>>     UnboundLocalError: cannot access local variable 'node' where it is not
>> associated with a value
>>
>> So you're fixing a crash bug, but that's perhaps less than clear from
>> the commit message.
>>
>> >                        If we don't have a section title, create a
>> > generic block to insert text into instead.
>> >
>> > This patch removes a lingering pylint warning in the QAPIDoc implementation
>>
>> Can you show me the warning?  My pylint doesn't...
>>
>> > that prevents getting a clean baseline to use for forthcoming
>> > additions.
>> >
>> > I am not attempting to *fully* clean up the existing QAPIDoc
>> > implementation in pylint because I intend to delete it anyway; this
>> > patch merely accomplishes a baseline under a specific pylint
>> > configuration:
>> >
>> > PYTHONPATH=../../scripts/ pylint --disable=fixme,too-many-lines,\
>> >     consider-using-f-string,missing-docstring,unused-argument,\
>> >     too-many-arguments,too-many-positional-arguments,\
>> >     too-many-public-methods \
>> >     qapidoc.py
>>
>> What version of pylint?  Mine chokes on too-many-positional-arguments.
>
> 3.3.1 here; if yours doesn't have that warning, there's no need to disable
> it. just remove that flag from the CLI.

I've since upgraded to  3.3.3, which doesn't choke.

> (I promise I do want to get this rigorously checked and automated, I'm
> sorry it's taken so long to achieve.)

[...]