[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH 3/5] qapi: add qapi2texi script
From: |
Marc-André Lureau |
Subject: |
Re: [Qemu-devel] [PATCH 3/5] qapi: add qapi2texi script |
Date: |
Mon, 27 Jul 2015 19:39:20 -0400 (EDT) |
Hi
----- Original Message -----
> On 07/03/2015 03:51 AM, Marc-André Lureau wrote:
> > From: Marc-André Lureau <address@hidden>
> >
> > 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 <address@hidden>
> > ---
> > 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
>
>
- [Qemu-devel] [PATCH 0/5] RFC: generate QAPI doc from json, Marc-André Lureau, 2015/07/03
- [Qemu-devel] [PATCH 1/5] qapi: add comment block before ChardevDummy, Marc-André Lureau, 2015/07/03
- [Qemu-devel] [PATCH 2/5] qapi: add missing @, Marc-André Lureau, 2015/07/03
- [Qemu-devel] [PATCH 3/5] qapi: add qapi2texi script, Marc-André Lureau, 2015/07/03
- [Qemu-devel] [PATCH 4/5] texi2pod: learn quotation, deftp and deftypefn, Marc-André Lureau, 2015/07/03
- [Qemu-devel] [PATCH 5/5] build-sys: generate QAPI doc based on json, Marc-André Lureau, 2015/07/03