On 09/22/2016 10:58 AM, Marc-André Lureau wrote: > 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: > # | $ echo foo > # | <- do this > # | -> get that
Arrows are backwards; should be -> do this, <- get that.
> #
> ##
>
> ##
> # @symbol
> #
> # Symbol body ditto ergo sum. Foo bar
> # baz ding.
> #
> # @arg: foo
> # @arg: #optional foo
> #
> # Returns: returns bla bla
> #
> # Or bla blah
> #
> # Since: version
> # Notes: notes, comments can have
> # - itemized list
> # - like this
> #
> # and continue...
> #
> # Example:
> #
> # -> { "execute": "quit" }
> # <- { "return": {} }
> #
> ##
>
> 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 <marcandre.lur...@redhat.com>
> ---
> scripts/qapi.py | 90 ++++++++++++++-
> scripts/qapi2texi.py | 307
> +++++++++++++++++++++++++++++++++++++++++++++++++
> docs/qapi-code-gen.txt | 44 +++++--
> 3 files changed, 429 insertions(+), 12 deletions(-)
> create mode 100755 scripts/qapi2texi.py
Not a close review at this point, so much as first impressions...
> +++ b/scripts/qapi2texi.py
> @@ -0,0 +1,307 @@
> +#!/usr/bin/env python
> +# QAPI texi generator
> +#
> +# This work is licensed under the terms of the GNU GPL, version 2.
Can you fix this to GPLv2+? Our GPLv2-only scripts were a mistake that
should not be repeated.
> +++ b/docs/qapi-code-gen.txt
> @@ -45,16 +45,13 @@ QAPI parser does not). At present, there is no place
> where a QAPI
> schema requires the use of JSON numbers or null.
>
> Comments are allowed; anything between an unquoted # and the following
> -newline is ignored. Although there is not yet a documentation
> -generator, a form of stylized comments has developed for consistently
> -documenting details about an expression and when it was added to the
> -schema. The documentation is delimited between two lines of ##, then
> -the first line names the expression, an optional overview is provided,
> -then individual documentation about each member of 'data' is provided,
> -and finally, a 'Since: x.y.z' tag lists the release that introduced
> -the expression. Optional members are tagged with the phrase
> -'#optional', often with their default value; and extensions added
> -after the expression was first released are also given a '(since
> +newline is ignored. The documentation is delimited between two lines
> +of ##, then the first line names the expression, an optional overview
> +is provided, then individual documentation about each member of 'data'
> +is provided, and finally, a 'Since: x.y.z' tag lists the release that
> +introduced the expression. Optional members are tagged with the
> +phrase '#optional', often with their default value; and extensions
> +added after the expression was first released are also given a '(since
> x.y.z)' comment. For example:
>
> ##
> @@ -73,12 +70,39 @@ x.y.z)' comment. For example:
> # (Since 2.0)
> #
> # Since: 0.14.0
> + #
> + # Notes: You can also make a list:
> + # - with items
> + # - like this
> + #
> + # Example:
> + #
> + # -> { "execute": ... }
> + # <- { "return": ... }
> + #
> ##
Thanks for remembering this. It does no good to parse a nebulous format,
but calling out the format means we have something to copy from and to
bring existing outliers into conformance.
> { 'struct': 'BlockStats',
> 'data': {'*device': 'str', 'stats': 'BlockDeviceStats',
> '*parent': 'BlockStats',
> '*backing': 'BlockStats'} }
>
> +It's also possible to create documentation sections, such as:
> +
> + ##
> + # = Section
> + # == Subsection
> + #
> + # Some text foo with *emphasis*
> + # 1. with a list
> + # 2. like that
> + #
> + # And some code:
> + # | $ echo foo
> + # | <- do this
> + # | -> get that
Again, arrows look backwards here.
--
Eric Blake eblake redhat com +1-919-301-3266
Libvirt virtualization library http://libvirt.org
signature.asc
Description: OpenPGP digital signature
