From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:45216) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn6oG-00007b-Dp for qemu-devel@nongnu.org; Thu, 22 Sep 2016 12:25:17 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bn6oD-0003Xv-59 for qemu-devel@nongnu.org; Thu, 22 Sep 2016 12:25:16 -0400 Received: from mx1.redhat.com ([209.132.183.28]:41202) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bn6oC-0003XZ-Sh for qemu-devel@nongnu.org; Thu, 22 Sep 2016 12:25:13 -0400 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 0B16032D3B7 for ; Thu, 22 Sep 2016 16:25:12 +0000 (UTC) References: <20160922155808.8504-1-marcandre.lureau@redhat.com> <20160922155808.8504-2-marcandre.lureau@redhat.com> From: Eric Blake Message-ID: <654f6e24-fcc8-a9cc-fc3f-d9c44fc44029@redhat.com> Date: Thu, 22 Sep 2016 11:25:10 -0500 MIME-Version: 1.0 In-Reply-To: <20160922155808.8504-2-marcandre.lureau@redhat.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="LdFwoJwTgsQSNjebnjVt5wW6T0pTxmdl8" Subject: Re: [Qemu-devel] [PATCH 1/4] qapi: add qapi2texi script List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?UTF-8?Q?Marc-Andr=c3=a9_Lureau?= , qemu-devel@nongnu.org Cc: armbru@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --LdFwoJwTgsQSNjebnjVt5wW6T0pTxmdl8 From: Eric Blake To: =?UTF-8?Q?Marc-Andr=c3=a9_Lureau?= , qemu-devel@nongnu.org Cc: armbru@redhat.com Message-ID: <654f6e24-fcc8-a9cc-fc3f-d9c44fc44029@redhat.com> Subject: Re: [PATCH 1/4] qapi: add qapi2texi script References: <20160922155808.8504-1-marcandre.lureau@redhat.com> <20160922155808.8504-2-marcandre.lureau@redhat.com> In-Reply-To: <20160922155808.8504-2-marcandre.lureau@redhat.com> Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable On 09/22/2016 10:58 AM, Marc-Andr=C3=A9 Lureau wrote: > As the name suggests, the qapi2texi script converts JSON QAPI > description into a standalone texi file suitable for different target > formats. >=20 > It parses the following kind of blocks with some little variations: >=20 > ## > # =3D Section > # =3D=3D 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. > # > ## >=20 > ## > # @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": {} } > # > ## >=20 > Thanks to the json declaration, it's able to give extra information > about the type of arguments and return value expected. >=20 > Signed-off-by: Marc-Andr=C3=A9 Lureau > --- > 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 pla= ce where a QAPI > schema requires the use of JSON numbers or null. > =20 > 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: > =20 > ## > @@ -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'} } > =20 > +It's also possible to create documentation sections, such as: > + > + ## > + # =3D Section > + # =3D=3D 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. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --LdFwoJwTgsQSNjebnjVt5wW6T0pTxmdl8 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJX5AXmAAoJEKeha0olJ0NqHuEH/R8Cfs/clCKyxCvHXAhmQ2yP /F+kuY9Skplf6HazzL2DiCfkPPNfXzjP990wzeAQyoLQYOaNIXc4lXYOtpsoKTrg 7ef0do8989jYnVgzmMQI750oEEczMBsm5mFJI7JuF8UR0D9/taqf4FOU8Y/Thz+o WKDDATZj11M+UA+qUl7HCgL04d0ZpYznQSHOYPSo4bDnEp9FaovNmopKDmrnihY4 xtAd8/GoIW4WvJXAPrbM7M88HnstdHKd9zH3KQlQE+HooImac/uLJOESjt6nnMfv Af0SML4KKOl11t1Ps+lbR2rClocouRhJabdrIiw/iYq0RvDx9FsNJbqonG70k6M= =81qs -----END PGP SIGNATURE----- --LdFwoJwTgsQSNjebnjVt5wW6T0pTxmdl8--