On 07/03/2015 03:51 AM, Marc-André Lureau wrote: > From: Marc-André Lureau <marcandre.lur...@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.
>
> ##
> # @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.lur...@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?
>
> 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).
> @@ -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.
> +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
signature.asc
Description: OpenPGP digital signature
