Re: [PATCH v2 01/13] tests/qapi: generate output in source order
On Mon, May 4, 2026 at 5:50 AM Markus Armbruster wrote:
>
> John Snow writes:
>
> > Rewrite the test doc generator to produce output in source order instead
> > of arbitrarily by section name.
>
> Yes, please! Looks like leftovers from commit 8d789c8cdb8 (docs/sphinx:
> remove legacy QAPI manual generator).
> >
> > This patch removes our last use of the "body" field, which has an effect
> > on how the first plaintext section of each test documented is printed:
>
> What do you mean by "test documented"? The sentence makes sense to me
> if I drop "documented".
Thinko. Probably meant "each test documentation section" and short-circuited.
>
> > we now print "section=Plain" followed by the section text instead of
> > "body=[...]".
> >
> > This patch is motivated by a desire to move the QAPIDoc API away from
> > named fields for specific sections in a bid to force all users to simply
> > iterate through all_sections in order, instead - and to remove the named
> > subsections.
> >
> > Signed-off-by: John Snow
> > ---
> > tests/qapi-schema/doc-good.out | 26 +-
> > tests/qapi-schema/test-qapi.py | 15 ---
> > 2 files changed, 21 insertions(+), 20 deletions(-)
> >
> > diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> > index 04a55072646..e2be6f96bbf 100644
> > --- a/tests/qapi-schema/doc-good.out
> > +++ b/tests/qapi-schema/doc-good.out
> > @@ -54,15 +54,15 @@ event EVT_BOXED Object
> > boxed=True
> > feature feat3
> > doc freeform
> > -body=
> > +section=Plain
> > ***
> > Section
> > ***
> > doc freeform
> > -body=
> > +section=Plain
> > Just text, no heading.
> > doc freeform
> > -body=
> > +section=Plain
> > Subsection
> > ==
> >
> > @@ -106,7 +106,7 @@ Examples:
> > - *verbatim*
> > - {braces}
> > doc symbol=Enum
> > -body=
> > +section=Plain
> >
> > arg=one
> > The _one_ {and only}, description on the same line
> > @@ -119,13 +119,13 @@ a member feature
> > section=Plain
> > @two is undocumented
> > doc symbol=Base
> > -body=
> > +section=Plain
> >
> > arg=base1
> > description starts on a new line,
> > minimally indented
> > doc symbol=Variant1
> > -body=
> > +section=Plain
> > A paragraph
> >
> > Another paragraph
> > @@ -138,15 +138,15 @@ a feature
> > feature=member-feat
> > a member feature
> > doc symbol=Variant2
> > -body=
> > +section=Plain
> >
> > doc symbol=Object
> > -body=
> > +section=Plain
> >
> > feature=union-feat1
> > a feature
> > doc symbol=Alternate
> > -body=
> > +section=Plain
> >
> > arg=i
> > description starts on the same line
> > @@ -157,11 +157,11 @@ description starts on the same line
> > feature=alt-feat
> > a feature
> > doc freeform
> > -body=
> > +section=Plain
> > Another subsection
> > ==
> > doc symbol=cmd
> > -body=
> > +section=Plain
> >
> > arg=arg1
> > description starts on a new line,
> > @@ -210,7 +210,7 @@ Note::
> > section=Since
> > 2.10
> > doc symbol=cmd-boxed
> > -body=
> > +section=Plain
> > If you're bored enough to read this, go see a video of boxed cats
> > feature=cmd-feat1
> > a feature
> > @@ -223,7 +223,7 @@ another feature
> >
> > <- ... has no title ...
> > doc symbol=EVT_BOXED
> > -body=
> > +section=Plain
> >
> > feature=feat3
> > a feature
> > diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
> > index cf7fb8a6df5..27885147b4d 100755
> > --- a/tests/qapi-schema/test-qapi.py
> > +++ b/tests/qapi-schema/test-qapi.py
> > @@ -19,6 +19,7 @@
> > from io import StringIO
> >
> > from qapi.error import QAPIError
> > +from qapi.parser import QAPIDoc
> > from qapi.schema import QAPISchema, QAPISchemaVisitor
> >
> >
> > @@ -116,13 +117,13 @@ def test_frontend(fname):
> > print('doc symbol=%s' % doc.symbol)
> > else:
> > print('doc freeform')
> > -print('body=\n%s' % doc.body.text)
> > -for arg, section in doc.args.items():
> > -print('arg=%s\n%s' % (arg, section.text))
> > -for feat, section in doc.features.items():
> > -print('feature=%s\n%s' % (feat, section.text))
> > -for section in doc.sections:
> > -print('section=%s\n%s' % (section.kind, section.text))
> > +for section in doc.all_sections:
> > +if section.kind == QAPIDoc.Kind.MEMBER:
> > +print('arg=%s\n%s' % (section.name, section.text))
> > +elif section.kind == QAPIDoc.Kind.FEATURE:
> > +print('feature=%s\n%s' % (section.name, section.text))
> > +else:
> > +print('section=%s\n%s' % (section.kind, section.text))
> >
> >
> > def open_test_result(dir_name, file_name, update):
>
> The loop body could be dumbed down further:
>
>
Re: [PATCH v2 01/13] tests/qapi: generate output in source order
John Snow writes:
> Rewrite the test doc generator to produce output in source order instead
> of arbitrarily by section name.
Yes, please! Looks like leftovers from commit 8d789c8cdb8 (docs/sphinx:
remove legacy QAPI manual generator).
>
> This patch removes our last use of the "body" field, which has an effect
> on how the first plaintext section of each test documented is printed:
What do you mean by "test documented"? The sentence makes sense to me
if I drop "documented".
> we now print "section=Plain" followed by the section text instead of
> "body=[...]".
>
> This patch is motivated by a desire to move the QAPIDoc API away from
> named fields for specific sections in a bid to force all users to simply
> iterate through all_sections in order, instead - and to remove the named
> subsections.
>
> Signed-off-by: John Snow
> ---
> tests/qapi-schema/doc-good.out | 26 +-
> tests/qapi-schema/test-qapi.py | 15 ---
> 2 files changed, 21 insertions(+), 20 deletions(-)
>
> diff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out
> index 04a55072646..e2be6f96bbf 100644
> --- a/tests/qapi-schema/doc-good.out
> +++ b/tests/qapi-schema/doc-good.out
> @@ -54,15 +54,15 @@ event EVT_BOXED Object
> boxed=True
> feature feat3
> doc freeform
> -body=
> +section=Plain
> ***
> Section
> ***
> doc freeform
> -body=
> +section=Plain
> Just text, no heading.
> doc freeform
> -body=
> +section=Plain
> Subsection
> ==
>
> @@ -106,7 +106,7 @@ Examples:
> - *verbatim*
> - {braces}
> doc symbol=Enum
> -body=
> +section=Plain
>
> arg=one
> The _one_ {and only}, description on the same line
> @@ -119,13 +119,13 @@ a member feature
> section=Plain
> @two is undocumented
> doc symbol=Base
> -body=
> +section=Plain
>
> arg=base1
> description starts on a new line,
> minimally indented
> doc symbol=Variant1
> -body=
> +section=Plain
> A paragraph
>
> Another paragraph
> @@ -138,15 +138,15 @@ a feature
> feature=member-feat
> a member feature
> doc symbol=Variant2
> -body=
> +section=Plain
>
> doc symbol=Object
> -body=
> +section=Plain
>
> feature=union-feat1
> a feature
> doc symbol=Alternate
> -body=
> +section=Plain
>
> arg=i
> description starts on the same line
> @@ -157,11 +157,11 @@ description starts on the same line
> feature=alt-feat
> a feature
> doc freeform
> -body=
> +section=Plain
> Another subsection
> ==
> doc symbol=cmd
> -body=
> +section=Plain
>
> arg=arg1
> description starts on a new line,
> @@ -210,7 +210,7 @@ Note::
> section=Since
> 2.10
> doc symbol=cmd-boxed
> -body=
> +section=Plain
> If you're bored enough to read this, go see a video of boxed cats
> feature=cmd-feat1
> a feature
> @@ -223,7 +223,7 @@ another feature
>
> <- ... has no title ...
> doc symbol=EVT_BOXED
> -body=
> +section=Plain
>
> feature=feat3
> a feature
> diff --git a/tests/qapi-schema/test-qapi.py b/tests/qapi-schema/test-qapi.py
> index cf7fb8a6df5..27885147b4d 100755
> --- a/tests/qapi-schema/test-qapi.py
> +++ b/tests/qapi-schema/test-qapi.py
> @@ -19,6 +19,7 @@
> from io import StringIO
>
> from qapi.error import QAPIError
> +from qapi.parser import QAPIDoc
> from qapi.schema import QAPISchema, QAPISchemaVisitor
>
>
> @@ -116,13 +117,13 @@ def test_frontend(fname):
> print('doc symbol=%s' % doc.symbol)
> else:
> print('doc freeform')
> -print('body=\n%s' % doc.body.text)
> -for arg, section in doc.args.items():
> -print('arg=%s\n%s' % (arg, section.text))
> -for feat, section in doc.features.items():
> -print('feature=%s\n%s' % (feat, section.text))
> -for section in doc.sections:
> -print('section=%s\n%s' % (section.kind, section.text))
> +for section in doc.all_sections:
> +if section.kind == QAPIDoc.Kind.MEMBER:
> +print('arg=%s\n%s' % (section.name, section.text))
> +elif section.kind == QAPIDoc.Kind.FEATURE:
> +print('feature=%s\n%s' % (section.name, section.text))
> +else:
> +print('section=%s\n%s' % (section.kind, section.text))
>
>
> def open_test_result(dir_name, file_name, update):
The loop body could be dumbed down further:
if isinstance(section, QAPIDoc.ArgSection):
print('%s=%s' % (section.kind, section.name))
else:
print('%s' % section.kind)
print(section.text)
Expected output changes a bit more then. I don't mind.
