From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:47305) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WW0Na-0003QI-Ba for qemu-devel@nongnu.org; Fri, 04 Apr 2014 05:25:47 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WW0NV-0002bt-Im for qemu-devel@nongnu.org; Fri, 04 Apr 2014 05:25:42 -0400 Received: from mx1.redhat.com ([209.132.183.28]:61893) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WW0NV-0002bj-BD for qemu-devel@nongnu.org; Fri, 04 Apr 2014 05:25:37 -0400 Message-ID: <533E7A8C.60301@redhat.com> Date: Fri, 04 Apr 2014 11:25:32 +0200 From: Paolo Bonzini MIME-Version: 1.0 References: In-Reply-To: Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Subject: Re: [Qemu-devel] Documentation tools for QEMU List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Anirudha Bose , qemu-devel 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 > ? Have you considered using Spinx for this purpose? No, you know more than I do it seems. :) Paolo