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
