Re: [Qemu-devel] [PATCH 3/5] qapi: add qapi2texi script

["Marc-André Lureau" <mlureau@redhat.com>]

Hi

----- Original Message -----
> On 07/03/2015 03:51 AM, Marc-André Lureau wrote:
> > From: Marc-André Lureau <marcandre.lureau@gmail.com>
> > 
> > As the name suggests, the qapi2texi script converts JSON QAPI
> > description into a standalone texi file suitable for different target
> > formats.
> > 
> > As the documentation format doesn't seem to be specified, it parses the
> > following blocks before each declaration with some variations:
> 
> docs/qapi-code-gen.txt tried to give a sample documentation.  Feel free
> to formalize that, and to fix non-conforming uses, if you desire.  It'll
> be a big one-time audit of the .json files, but getting things
> consistent, _and keeping them that way by automatic conformance checks
> in your conversion tool_, is fine by me.

Thanks, the patch series evolved quite a bit since this first series.

The current branch is: https://github.com/elmarco/qemu/commits/qapi

And I found about that doc, so I removed that comment in commit message.
 
> > 
> >   ##
> >   # @symbol
> >   #
> >   # body
> >   #
> >   # @arg: foo
> >   # @arg: #optional foo
> >   #
> >   # Returns: returns
> >   # Since: version
> >   # Notes: notes
> >   ##
> > 
> > Using the json declaration, it's able to give extra information about
> > the type of arguments and return value expected.
> > 
> > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
> > ---
> >  scripts/qapi.py      |  78 ++++++++++++++++++-
> >  scripts/qapi2texi.py | 212
> >  +++++++++++++++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 286 insertions(+), 4 deletions(-)
> >  create mode 100644 scripts/qapi2texi.py
> 
> Are you intending to apply this after Markus' big work on QMP Introspection?

Yes, I am in contact with Markus, I propose we revisit this series after his patches are merged.

Thanks for your comments so far, 

> > 
> > diff --git a/scripts/qapi.py b/scripts/qapi.py
> > index 06d7fc2..70208e8 100644
> > --- a/scripts/qapi.py
> > +++ b/scripts/qapi.py
> > @@ -103,6 +103,53 @@ class QAPIExprError(Exception):
> >          return error_path(self.info['parent']) + \
> >              "%s:%d: %s" % (self.info['file'], self.info['line'], self.msg)
> >  
> > +class QAPIDoc:
> 
> In particular, this should probably be QAPIDoc(object) (new style class
> declaration).

I just run pep8 fine on my file, I don't know about that new syntax.

> 
> > @@ -762,6 +823,15 @@ def parse_schema(fname):
> >          print >>sys.stderr, e
> >          exit(1)
> >  
> > +def parse_schema_full(fname):
> > +    try:
> > +        schema = QAPISchema(open(fname, "r"))
> > +        check_exprs(schema.exprs)
> > +        return schema.exprs
> > +    except (QAPISchemaError, QAPIExprError), e:
> > +        print >>sys.stderr, e
> > +        exit(1)
> 
> and this may need to be reworked on top of Markus' new parser class.
> 
> > +++ b/scripts/qapi2texi.py
> > @@ -0,0 +1,212 @@
> > +# QAPI texi generator
> > +#
> > +# This work is licensed under the terms of the GNU GPL, version 2.
> > +# See the COPYING file in the top-level directory.
> 
> Although I'm not a lawyer, my understanding is that for GPL to apply,
> there has to be an explicit mention of Copyright.
> 

ah ok, I'll add it then


> > +exprs = parse_schema_full(sys.argv[4])
> 
> And you'll probably want to rewrite this in terms of the visitor interface.
> 
> > +for cmd in exprs:
> > +    expr = cmd['expr']
> > +    docs = cmd['info']['doc']
> > +    (kind, name) = expr.items()[0]
> > +
> > +    for d in docs[0:-1]:
> > +        print d.comment
> > +
> > +    texi = {"command": texi_command,
> > +            "struct": texi_struct,
> > +            "enum": texi_enum,
> > +            "union": texi_union,
> > +            "alternate": texi_alternate,
> > +            "event": texi_event}
> > +    try:
> > +        texi[kind](expr, docs[-1])
> > +    except KeyError:
> > +        raise ValueError("Unknown expression kind '%s'" % kind)
> 
> although this is a rather cute way to polymorphically invoke the correct
> helper function.
> 
> --
> Eric Blake   eblake redhat com    +1-919-301-3266
> Libvirt virtualization library http://libvirt.org
> 
>