On Wed, Feb 26, 2025, 4:37 AM Markus Armbruster <arm...@redhat.com> wrote:
> Markus Armbruster <arm...@redhat.com> writes: > > > John Snow <js...@redhat.com> writes: > > > >> The code as written crashes when a free-form documentation block doesn't > >> start with a heading or subheading, for example: > >> > >> | ## > >> | # Just text, no heading. > >> | ## > >> > >> The code will attempt to use the `node` variable uninitialized. To fix, > >> create a generic block to insert the doc text into. > >> > >> (This patch also removes a lingering pylint warning in the QAPIDoc > >> implementation that prevents getting a clean baseline to use for > >> forthcoming additions.) > >> > >> Fixes: 43e0d14ee09a (docs/sphinx: fix extra stuff in TOC after freeform > QMP sections) > >> 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 > > > > Let's add a suitable free-form block to tests/qapi-schema/doc-good.json > > to catch regressions. Not worth a respin by itself. > > With the appended obvious fixup: > Reviewed-by: Markus Armbruster <arm...@redhat.com> > > > diff --git a/tests/qapi-schema/doc-good.json > b/tests/qapi-schema/doc-good.json > index f64bf38d85..0a4f139f83 100644 > --- a/tests/qapi-schema/doc-good.json > +++ b/tests/qapi-schema/doc-good.json > @@ -11,6 +11,10 @@ > # = Section > ## > > +## > +# Just text, no heading. > +## > + > ## > # == Subsection > # > diff --git a/tests/qapi-schema/doc-good.out > b/tests/qapi-schema/doc-good.out > index ec277be91e..0a9da3efde 100644 > --- a/tests/qapi-schema/doc-good.out > +++ b/tests/qapi-schema/doc-good.out > @@ -56,6 +56,9 @@ event EVT_BOXED Object > doc freeform > body= > = Section > +doc freeform > + body= > +Just text, no heading. > doc freeform > body= > == Subsection > Sold! >
