| Message ID | 20241213021827.2956769-2-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: add basic sphinx-domain rST generator to qapidoc | expand |
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. > 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 :)
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
The code as written can't handle if a header isn't found, because `node` will be uninitialized. 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 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 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(+)