On Mon, Dec 16, 2024 at 8:15 AM Markus Armbruster <arm...@redhat.com> wrote:
> John Snow <js...@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 <js...@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 :) > >
