Re: [Qemu-devel] [PATCH 08/36] qapi: add qapi2texi script

[Eric Blake]

On 09/25/2015 08:03 AM, address@hidden 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.
> 
> It parses the following kind of blocks with some little variations:
> 
>   ##
>   # = Section
>   # == Subsection
>   #
>   # Some text foo with *emphasis*
>   # 1. with a list
>   # 2. like that
>   #
>   # And some code:
>   # | <- do this
>   # | -> get that

Backwards; you mean:

# | -> send this
# | <- get that


>   # Example:
>   #
>   # -> { "execute": "quit" }
>   # <- { "return": {} }
>   #

but this one is right.

I'd love to have this formalized semantics of what you plan to parse
documented in docs/qapi-code-gen.txt, as a reference we can point to for
new commands that don't comply.

> Thanks to 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      |  88 +++++++++++++++-
>  scripts/qapi2texi.py | 293 
> +++++++++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 379 insertions(+), 2 deletions(-)
>  create mode 100755 scripts/qapi2texi.py

I will forbear the actual review detailed for now, in part because it
may need another rebase, but the idea seems nice.  But I'll do a quick
read-through review:

> 
> diff --git a/scripts/qapi.py b/scripts/qapi.py
> index 27894c1..2a9b6e5 100644
> --- a/scripts/qapi.py
> +++ b/scripts/qapi.py
> @@ -112,6 +112,67 @@ class QAPIExprError(Exception):
>              "%s:%d: %s" % (self.info['file'], self.info['line'], self.msg)
>  
>  
> +class QAPIDoc:

Use the new-style class inheritance (as in "class QAPIDoc(object):")


> +++ b/scripts/qapi2texi.py
> @@ -0,0 +1,293 @@
> +#!/usr/bin/env python
> +# QAPI texi generator
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2.

Can we please use GPLv2+ for this file? GPLv2-only is a pain (yes,
qapi.py is stuck there unless someone does legwork to see if former
contributors don't mind relaxing it, but that doesn't mean we have to
repeat the mistake)

-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature