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 promise I do want to get this rigorously checked and automated, I'm
sorry it's taken so long to achieve.)
>
> > This at least ensures there aren't regressions outside of these general
> > warnings in the new qapidoc.py code to be committed.
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
> > ---
> > docs/sphinx/qapidoc.py | 2 ++
> > 1 file changed, 2 insertions(+)
> >
> > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py
> > index 5f96b46270b..5a4d7388b29 100644
> > --- a/docs/sphinx/qapidoc.py
> > +++ b/docs/sphinx/qapidoc.py
> > @@ -421,6 +421,8 @@ def freeform(self, doc):
> > node = self._start_new_heading(heading, len(leader))
> > if text == '':
> > return
> > + else:
> > + node = nodes.container()
> >
> > self._parse_text_into_node(text, node)
> > self._cur_doc = None
>
> Plausible enough (and I acked a similar fix previously, commit
> 2664f3176a8), but I'm a Sphinx ignoramus :)
>
>