Re: [Qemu-devel] [PATCH 00/30] Move qapi documentation to schema (part 1/5)

[Markus Armbruster]

Marc-André Lureau <address@hidden> 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.