From patchwork Thu May 12 15:58:19 2011 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anthony Liguori X-Patchwork-Id: 95336 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.gnu.org (lists.gnu.org [140.186.70.17]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (Client did not present a certificate) by ozlabs.org (Postfix) with ESMTPS id 0C994B6F67 for ; Fri, 13 May 2011 01:58:44 +1000 (EST) Received: from localhost ([::1]:48829 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYHg-0000yS-Fn for incoming@patchwork.ozlabs.org; Thu, 12 May 2011 11:58:40 -0400 Received: from eggs.gnu.org ([140.186.70.92]:48894) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYHV-0000yH-ET for qemu-devel@nongnu.org; Thu, 12 May 2011 11:58:33 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1QKYHO-0005gG-Nh for qemu-devel@nongnu.org; Thu, 12 May 2011 11:58:29 -0400 Received: from mail-yx0-f173.google.com ([209.85.213.173]:42139) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1QKYHO-0005gB-Kq for qemu-devel@nongnu.org; Thu, 12 May 2011 11:58:22 -0400 Received: by yxk8 with SMTP id 8so679561yxk.4 for ; Thu, 12 May 2011 08:58:21 -0700 (PDT) Received: by 10.150.73.9 with SMTP id v9mr513264yba.138.1305215901487; Thu, 12 May 2011 08:58:21 -0700 (PDT) Received: from [192.168.0.107] (cpe-70-123-132-139.austin.res.rr.com [70.123.132.139]) by mx.google.com with ESMTPS id c3sm785140ybn.18.2011.05.12.08.58.20 (version=TLSv1/SSLv3 cipher=OTHER); Thu, 12 May 2011 08:58:20 -0700 (PDT) Message-ID: <4DCC039B.5070608@codemonkey.ws> Date: Thu, 12 May 2011 10:58:19 -0500 From: Anthony Liguori User-Agent: Mozilla/5.0 (X11; U; Linux x86_64; en-US; rv:1.9.2.17) Gecko/20110424 Lightning/1.0b2 Thunderbird/3.1.10 MIME-Version: 1.0 To: Gerd Hoffmann References: <1305023443-8722-1-git-send-email-kraxel@redhat.com> <201105101624.08253.bradh@frogmouth.net> <4DCBA79B.5040608@redhat.com> <4DCBFBFF.7000203@redhat.com> In-Reply-To: <4DCBFBFF.7000203@redhat.com> X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 2) X-Received-From: 209.85.213.173 Cc: amit.shah@redhat.com, Markus Armbruster , Brad Hards , qemu-devel@nongnu.org Subject: Re: [Qemu-devel] qdev device documentation (Re: [PATCH 0/2] usb-linux: physical port handling.) X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.14 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org On 05/12/2011 10:25 AM, Gerd Hoffmann wrote: > Hi, > >>> What is the status of the qdev documentation patches btw.? >> >> http://lists.gnu.org/archive/html/qemu-devel/2011-02/msg02169.html > > What is the problem with the empty strings btw? > > The only way around I can see is having _DOC and _NODOC versions for all > the property macros, but I'd prefer to not have _NODOC macros in the > tree ... Here's an example of what I'm suggesting. I think we should just go with this and add better output as we go. But we need all of the qdev information.. not just a doc string for each property. Regards, Anthony Liguori > > cheers, > Gerd > > From 130c817790880c61b79dbccf66f5863c406eb7d4 Mon Sep 17 00:00:00 2001 From: Anthony Liguori Date: Thu, 12 May 2011 10:56:29 -0500 Subject: [PATCH] qdev: add centralized documentation for qdev This is mostly a proof-of-concept. Signed-off-by: Anthony Liguori diff --git a/Makefile b/Makefile index 2b0438c..fddb261 100644 --- a/Makefile +++ b/Makefile @@ -341,5 +341,7 @@ tarbin: $(mandir)/man1/qemu-img.1 \ $(mandir)/man8/qemu-nbd.8 +include $(SRC_PATH)/Makefile.doc + # Include automatically generated dependency files -include $(wildcard *.d audio/*.d slirp/*.d block/*.d net/*.d ui/*.d) diff --git a/Makefile.doc b/Makefile.doc new file mode 100644 index 0000000..f769b23 --- /dev/null +++ b/Makefile.doc @@ -0,0 +1,2 @@ +qdev-doc.html: $(SRC_PATH)/qdev-doc.json + python $(SRC_PATH)/scripts/qdev-doc-to-html.py < $< > $@ diff --git a/qdev-doc.json b/qdev-doc.json new file mode 100644 index 0000000..c24630b --- /dev/null +++ b/qdev-doc.json @@ -0,0 +1,14 @@ +# -*- Mode: Python -*- + +[ { "device": "isa-serial", + "parent": "ISADevice", + "properties": { + "index": { "type": "uint32", + "doc": "A value from 0-3 that describes which IO regions to expose the device on. This sets appropriate values for iobase and irq." }, + "iobase": { "type": "hex32", + "doc": "The base IO address to expose the device on." }, + "irq": { "type": "uint32", + "doc": "The IRQ to use for the device." }, + "chardev": { "type": "chr", + "doc": "The name of a character device to specify." } } } + ] diff --git a/scripts/qdev-doc-to-html.py b/scripts/qdev-doc-to-html.py new file mode 100644 index 0000000..a25fe35 --- /dev/null +++ b/scripts/qdev-doc-to-html.py @@ -0,0 +1,40 @@ +#!/usr/bin/python + +import sys + +data = sys.stdin.read() + +docs = eval(data) + +sys.stdout.write(''' + + +QEMU device documentation + + +''') + +for item in docs: + sys.stdout.write(''' +

%(device)s :: %(parent)s

+ + + + + +''' % item) + for prop in item["properties"]: + sys.stdout.write(''' + + + +''' % (prop, item["properties"][prop]['type'], item["properties"][prop]['doc'])) + + sys.stdout.write(''' +
NameTypeComments
%s%s%s
+''') + +sys.stdout.write(''' + + +''') -- 1.7.4.1