From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:35252) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjoIj-0000O9-VG for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:03:10 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1bjoId-0000fi-1m for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:03:04 -0400 Received: from mx1.redhat.com ([209.132.183.28]:39588) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1bjoIc-0000du-Sw for qemu-devel@nongnu.org; Tue, 13 Sep 2016 10:02:58 -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 877F863E25 for ; Tue, 13 Sep 2016 14:02:57 +0000 (UTC) From: Markus Armbruster References: <20160913130209.695-1-marcandre.lureau@redhat.com> Date: Tue, 13 Sep 2016 16:02:54 +0200 In-Reply-To: <20160913130209.695-1-marcandre.lureau@redhat.com> (=?utf-8?Q?=22Marc-Andr=C3=A9?= Lureau"'s message of "Tue, 13 Sep 2016 17:01:39 +0400") Message-ID: <87y42v5241.fsf@dusky.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5) List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau Cc: qemu-devel@nongnu.org Marc-Andr=C3=A9 Lureau writes: > Hi, > > The QAPI documentation is currently done in two places, the json > schema and a more human-friendly text file. The goal is to avoid > duplication and to generate friendly versions from the schema (pdf, > man etc). Thus, all documentation should be moved to the schema. > > In order to facilitate the review, the documentation move has been > splitted, and is going to sent by chunks of ~30 patches. This way it > should take about 5 series to complete (~150 patches). I suggest that > the qapi maintainers (Markus/Eric) compile the reviewed patches in a > branch and merge upstream in one go (either merging move commits or > not) when the series complete and the documentation is finally > generated to avoid an in-between state. > > The wip branch with all the pending patches: > https://github.com/elmarco/qemu/commits/qapi-doc Ah, now I understand why you asked whether to post everything! The "move FOO doc to schema" patches make no sense until the very end of the full branch, when you actually generate documentation from the schema. Perhaps you could structure like this: 1. Fix existing issues in QAPI schema comments 2. Generate documentation from it (not a replacement for qmp-commands.txt, yet) 3. Merge qmp-commands.txt into QAPI schema comments, step by step (a) If you only update the QAPI schema comments, qmp-commands.txt stays intact throughout this work. (b) If you delete qmp-commands.txt section as you cover them in the QAPI schema, command documentation regresses temporarily. Tolerable, but needs to be explained in commit messages. Your choice. 4. Generated documentation now contains everything qmp-commands.txt contains; delete qmp-commands.txt Getting to this structure with option (3b) could be as simple as reordering your branch. > And a sneak peek of the generated pdf documentation: > https://fedorapeople.org/~elmarco/qemu-qapi.pdf Looks slick :) > The series is currently based on Markus qapi-next branch.