SYS-OSS/FRET-qemu
4
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs/qapidoc: support header-less freeform sections

Browse Source 
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 <jsnow@redhat.com>
Message-ID: <20250224033741.222749-5-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Test updated to cover this]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-02-23 22:37:35 -05:00 committed by Markus Armbruster
parent 6a2c7fc29a
commit b61a4eb3f3
3 changed files with 9 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/sphinx/qapidoc.py
View File

@ -421,6 +421,8 @@ class QAPISchemaGenRSTVisitor(QAPISchemaVisitor):
node = self._start_new_heading(heading, len(leader)) node = self._start_new_heading(heading, len(leader))
if text == '': if text == '':
return return
else:
node = nodes.container()
self._parse_text_into_node(text, node) self._parse_text_into_node(text, node)
self._cur_doc = None self._cur_doc = None

4
tests/qapi-schema/doc-good.json
View File

@ -11,6 +11,10 @@
# = Section # = Section
## ##
##
# Just text, no heading.
##
## ##
# == Subsection # == Subsection
# #

3
tests/qapi-schema/doc-good.out
View File

@ -56,6 +56,9 @@ event EVT_BOXED Object
doc freeform doc freeform
body= body=
= Section = Section
doc freeform
body=
Just text, no heading.
doc freeform doc freeform
body= body=
== Subsection == Subsection