Re: [PATCH v2 01/13] tests/qapi: generate output in source order

[Markus Armbruster <armbru@redhat.com>]

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