Re: [Qemu-devel] Documentation tools for QEMU

[Paolo Bonzini]

Il 03/04/2014 20:56, Anirudha Bose ha scritto:
> Hi Paolo !
>
> I would like to volunteer to develop Documentation tools for QEMU during
> my summer holidays. Yesterday I had expressed my intent to work on this
> project in the IRC channel of QEMU. This is a follow up email of your reply.

That's awesome.  I've CCed qemu-devel so that other folks see what you'd 
like to do.

I'll be away for three weeks starting tomorrow, unfortunately, so making 
this public is even more important.

> We can use Pandoc to convert all the docs in different formats to HTML,
> rather than integrating all of them to qemu-tech.texi. We can do the
> same thing with other files as well like qemu-docs.texi and qemu-img.texi.
>
> A challenge in this project would be to process the plaintext files
> which have no styles defined in them. So rather than making the script
> do it, wouldn't it be better if all of them are rewritten in Markdown so
> that the final HTML will have a consistent look?

Yes, rewriting docs/ to Markdown is a good first step.

Some things you could do include:

- do the above Markdown rewrite, and test it with pandoc conversion to HTML

- send patches for it, so that you can get warm with the patches review 
process

- build a pandoc filter that converts @foo to `foo`.  I think there are 
examples in pandoc's homepage.

- look at command descriptions from qmp-commands.hx and start 
integrating missing information into qapi-schema.json.  Make 
qapi-schema.json doc comments much closer to Markdown (plus with the 
@foo syntax).

- study the QAPISchema class in scripts/qapi.py.  Start thinking of a 
qapi-schema.json -> Markdown converter and draft it in Python.  Later we 
can parse the JSON too, to include type information in the documentation.

- move *.texi files to docs/ and update the Makefile for it.

> What you expectations with this project? Would the final HTML
> documentation be hosted somewhere like readthedocs.org
> <http://readthedocs.org>? Have you considered using Spinx for this purpose?

No, you know more than I do it seems. :)

Paolo