[Qemu-devel] [PATCH v2 2/4] docs: add build infrastructure for gtkdocs (v2)

[Anthony Liguori]

By convention, documented headers now go in include/

Signed-off-by: Anthony Liguori <address@hidden>
---
v1 -> v2
 - Require the user to specify a path to the special gtk-doc tool
 - Better handling of includes
---
 Makefile        |    6 +++++-
 Makefile.docs   |   29 +++++++++++++++++++++++++++++
 Makefile.hw     |    1 +
 Makefile.target |    1 +
 QEMU-docs.xml   |   31 +++++++++++++++++++++++++++++++
 5 files changed, 67 insertions(+), 1 deletions(-)
 create mode 100644 Makefile.docs
 create mode 100644 QEMU-docs.xml

diff --git a/Makefile b/Makefile
index 2c03055..f6b068c 100644
--- a/Makefile
+++ b/Makefile
@@ -92,6 +92,8 @@ ifneq ($(wildcard config-host.mak),)
 include $(SRC_PATH)/Makefile.objs
 endif
 
+include $(SRC_PATH)/Makefile.docs
+
 $(common-obj-y): $(GENERATED_HEADERS)
 subdir-libcacard: $(oslib-obj-y) $(trace-obj-y) qemu-timer-common.o
 
@@ -113,6 +115,8 @@ QEMU_CFLAGS+=$(CURL_CFLAGS)
 
 QEMU_CFLAGS+=$(GLIB_CFLAGS)
 
+QEMU_CFLAGS+=-I$(SRC_PATH)/include
+
 ui/cocoa.o: ui/cocoa.m
 
 ui/sdl.o audio/sdlaudio.o ui/sdl_zoom.o baum.o: QEMU_CFLAGS += $(SDL_CFLAGS)
@@ -220,7 +224,7 @@ qemu-ga$(EXESUF): qemu-ga.o $(qga-obj-y) $(qapi-obj-y) 
$(tools-obj-y) $(qobject-
 
 QEMULIBS=libhw32 libhw64 libuser libdis libdis-user
 
-clean:
+clean: gtkdoc-clean
 # avoid old build problems by removing potentially incorrect old files
        rm -f config.mak op-i386.h opc-i386.h gen-op-i386.h op-arm.h opc-arm.h 
gen-op-arm.h
        rm -f qemu-options.def
diff --git a/Makefile.docs b/Makefile.docs
new file mode 100644
index 0000000..202b2c3
--- /dev/null
+++ b/Makefile.docs
@@ -0,0 +1,29 @@
+# -*- Mode: makefile -*-
+
+GTKDOC_SCAN=$(DOC_PREFIX)/gtkdoc-scan
+GTKDOC_MKDB=$(DOC_PREFIX)/gtkdoc-mkdb
+GTKDOC_MKHTML=$(DOC_PREFIX)/gtkdoc-mkhtml
+GTKDOC_FIXXREF=$(DOC_PREFIX)/gtkdoc-fixxref
+
+DOC_SRC=$(wildcard $(SRC_PATH)/include/*.h)
+
+ifeq ($(wildcard $(DOC_PREFIX)/gtkdoc-scan),)
+gtkdoc:
+       @echo Please set DOC_PREFIX before calling to a built version of:
+       @echo "  git://git.qemu.org/gtk-doc.git"
+       @exit 1
+else
+gtkdoc: html/index.html
+
+html/index.html: $(DOC_SRC)
+       $(GTKDOC_SCAN) --module=QEMU --source-dir=$(SRC_PATH)/include && \
+        cp $(SRC_PATH)/QEMU-docs.xml . && \
+       $(GTKDOC_MKDB) --module=QEMU --output-format=xml 
--source-dir=$(SRC_PATH)/include && \
+       mkdir -p html && \
+        (cd html && $(GTKDOC_MKHTML) QEMU ../QEMU-docs.xml && cd ..) && \
+       $(GTKDOC_FIXXREF) --module=QEMU --module-dir=html
+endif
+
+gtkdoc-clean:
+       $(RM) -r html xml
+       $(RM) $(SCAN_GEN) sgml.stamp *.bak html.stamp
diff --git a/Makefile.hw b/Makefile.hw
index 63eb7e4..7b8d068 100644
--- a/Makefile.hw
+++ b/Makefile.hw
@@ -11,6 +11,7 @@ $(call set-vpath, $(SRC_PATH):$(SRC_PATH)/hw)
 
 QEMU_CFLAGS+=-I..
 QEMU_CFLAGS += $(GLIB_CFLAGS)
+QEMU_CFLAGS += -I$(SRC_PATH)/include
 
 include $(SRC_PATH)/Makefile.objs
 
diff --git a/Makefile.target b/Makefile.target
index 8be9b9a..da8e668 100644
--- a/Makefile.target
+++ b/Makefile.target
@@ -19,6 +19,7 @@ ifdef CONFIG_LINUX
 QEMU_CFLAGS += -I../linux-headers
 endif
 QEMU_CFLAGS += -I.. -I$(TARGET_PATH) -DNEED_CPU_H
+QEMU_CFLAGS += -I$(SRC_PATH)/include
 
 include $(SRC_PATH)/Makefile.objs
 
diff --git a/QEMU-docs.xml b/QEMU-docs.xml
new file mode 100644
index 0000000..ddc827a
--- /dev/null
+++ b/QEMU-docs.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd";
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 
'http://www.w3.org/2003/XInclude'">
+]>
+<book id="index">
+  <bookinfo>
+    <title>QEMU Reference Manual</title>
+    <releaseinfo>
+      for QEMU 1.0.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" 
url="http://wiki.qemu.org/docs-internal/";>http://wiki.qemu.org/docs-internal/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>Core Device APIs</title>
+
+  </chapter>
+  <index id="api-index-full">
+    <title>API Index</title>
+    <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+  </index>
+  <index id="deprecated-api-index" role="deprecated">
+    <title>Index of deprecated API</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback 
/></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
-- 
1.7.4.1