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.
[PATCH v2 01/13] tests/qapi: generate output in source order
Rewrite the test doc generator to produce output in source order instead
of arbitrarily by section name.
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:
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):
--
2.54.0
