qapi: misc testing and doc patches

[PATCH 04/10] docs/qapidoc: support header-less freeform sections

Posted by John Snow 1 month, 1 week ago

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>
---
 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
-- 
2.48.1

Re: [PATCH 04/10] docs/qapidoc: support header-less freeform sections

Posted by Markus Armbruster 1 month, 1 week ago

John Snow <jsnow@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 <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

Let's add a suitable free-form block to tests/qapi-schema/doc-good.json
to catch regressions.  Not worth a respin by itself.

Re: [PATCH 04/10] docs/qapidoc: support header-less freeform sections

Posted by Markus Armbruster 1 month ago

Markus Armbruster <armbru@redhat.com> writes:

> John Snow <jsnow@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 <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
>
> 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 <armbru@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

Re: [PATCH 04/10] docs/qapidoc: support header-less freeform sections

Posted by John Snow 1 month ago

On Wed, Feb 26, 2025, 4:37 AM Markus Armbruster <armbru@redhat.com> wrote:

> Markus Armbruster <armbru@redhat.com> writes:
>
> > John Snow <jsnow@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 <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
> >
> > 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 <armbru@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!

>