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

[Markus Armbruster <armbru@redhat.com>]

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 :)