Generating documentation with gtk-doc

Makefile

@@ -1,6 +1,6 @@
 PACKAGE	= cpp
 VERSION	= 0.0.1
-SUBDIRS	= data include src
+SUBDIRS	= data doc include src
 RM	?= rm -f
 LN	?= ln -f
 TAR	?= tar -czvf
@@ -25,6 +25,13 @@ dist:
 		$(PACKAGE)-$(VERSION)/data/cpp.pc.in \
 		$(PACKAGE)-$(VERSION)/data/pkgconfig.sh \
 		$(PACKAGE)-$(VERSION)/data/project.conf \
+		$(PACKAGE)-$(VERSION)/doc/Makefile \
+		$(PACKAGE)-$(VERSION)/doc/GRAMMAR \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc.sh \
+		$(PACKAGE)-$(VERSION)/doc/project.conf \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/Makefile \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/cpp-docs.xml \
+		$(PACKAGE)-$(VERSION)/doc/gtkdoc/project.conf \
 		$(PACKAGE)-$(VERSION)/include/cpp.h \
 		$(PACKAGE)-$(VERSION)/include/Makefile \
 		$(PACKAGE)-$(VERSION)/include/project.conf \

doc/Makefile

@@ -0,0 +1,40 @@
+SUBDIRS	= gtkdoc
+TARGETS	= gtkdoc/cpp.types gtkdoc/sgml.stamp html/index.html
+PREFIX	= /usr/local
+DESTDIR	=
+RM	?= rm -f
+LN	?= ln -f
+MKDIR	?= mkdir -p
+INSTALL	?= install
+
+
+all: subdirs $(TARGETS)
+
+subdirs:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE)) || exit; done
+
+gtkdoc/cpp.types:
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/cpp.types"
+
+gtkdoc/sgml.stamp: gtkdoc/cpp.types
+	./gtkdoc.sh -P "$(PREFIX)" -- "gtkdoc/sgml.stamp"
+
+html/index.html: gtkdoc/cpp-docs.xml gtkdoc/sgml.stamp
+	./gtkdoc.sh -P "$(PREFIX)" -- "html/index.html"
+
+clean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) clean) || exit; done
+	$(RM) -- $(gtkdoc/cpp.types_OBJS) $(gtkdoc/sgml.stamp_OBJS) $(html/index.html_OBJS)
+
+distclean:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) distclean) || exit; done
+	$(RM) -- $(gtkdoc/cpp.types_OBJS) $(gtkdoc/sgml.stamp_OBJS) $(html/index.html_OBJS)
+	$(RM) -- $(TARGETS)
+
+install: $(TARGETS)
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) install) || exit; done
+
+uninstall:
+	@for i in $(SUBDIRS); do (cd $$i && $(MAKE) uninstall) || exit; done
+
+.PHONY: all subdirs clean distclean install uninstall

doc/gtkdoc.sh

@@ -0,0 +1,136 @@
+#!/bin/sh
+#$Id$
+#Copyright (c) 2012 Pierre Pronchery <khorben@defora.org>
+#
+#Redistribution and use in source and binary forms, with or without
+#modification, are permitted provided that the following conditions are met:
+#
+# * Redistributions of source code must retain the above copyright notice, this
+#   list of conditions and the following disclaimer.
+# * Redistributions in binary form must reproduce the above copyright notice,
+#   this list of conditions and the following disclaimer in the documentation
+#   and/or other materials provided with the distribution.
+#
+#THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+#AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+#IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+#DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+#FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+#DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+#SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+#CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+#OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+#OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#TODO:
+#- implement installing and uninstalling
+
+
+
+#variables
+PREFIX="/usr/local"
+. "../config.sh"
+DEBUG="_debug"
+GTKDOC_FIXXREF="gtkdoc-fixxref"
+GTKDOC_MKDB="gtkdoc-mkdb"
+GTKDOC_MKHTML="gtkdoc-mkhtml"
+GTKDOC_SCAN="gtkdoc-scan"
+INSTALL="install -m 0644"
+MKDIR="mkdir -p"
+MODULE="$PACKAGE"
+RM="rm -f"
+TOUCH="touch"
+
+
+#functions
+#debug
+_debug()
+{
+	echo $@
+	$@
+}
+
+
+#usage
+_usage()
+{
+	echo "Usage: gtkdoc.sh [-i|-u][-P prefix] target" 1>&2
+	return 1
+}
+
+
+#main
+install=0
+uninstall=0
+while getopts "iuP:" "name"; do
+	case "$name" in
+		i)
+			uninstall=0
+			install=1
+			;;
+		u)
+			install=0
+			uninstall=1
+			;;
+		P)
+			PREFIX="$2"
+			;;
+		?)
+			_usage
+			exit $?
+			;;
+	esac
+done
+shift $((OPTIND - 1))
+if [ $# -eq 0 ]; then
+	_usage
+	exit $?
+fi
+
+[ -z "$DATADIR" ] && DATADIR="$PREFIX/share"
+
+while [ $# -gt 0 ]; do
+	target="$1"
+	shift
+
+	#create
+	#determine the type
+	ext="${target##*.}"
+	ext="${ext#.}"
+	case "$ext" in
+		html)
+			$MKDIR "html" &&
+			(cd "html" &&
+				$DEBUG $GTKDOC_MKHTML "$MODULE" \
+					"../gtkdoc/$MODULE-docs.xml") &&
+			(cd "gtkdoc" &&
+				$DEBUG $GTKDOC_FIXXREF \
+					--module="$MODULE" \
+					--module-dir="../html" \
+					--html-dir="$DATADIR/doc/html/$MODULE")
+			;;
+		stamp)
+			(cd "gtkdoc" &&
+				$DEBUG $GTKDOC_MKDB \
+					--module="$MODULE" \
+					--output-dir="xml" \
+					--output-format="xml")
+			;;
+		types)
+			(cd ".." &&
+				$DEBUG $GTKDOC_SCAN \
+					--module="$MODULE" \
+					--source-dir="." \
+					--output-dir="doc/gtkdoc")
+			;;
+		*)
+			echo "$0: $target: Unknown type" 1>&2
+			exit 2
+			;;
+	esac
+	#XXX ignore errors
+	if [ $? -ne 0 ]; then
+		echo "$0: $target: Could not create documentation" 1>&2
+		install=0
+	fi
+	$TOUCH "$target"
+done

doc/gtkdoc/Makefile

@@ -0,0 +1,13 @@
+
+
+all:
+
+clean:
+
+distclean: clean
+
+install:
+
+uninstall:
+
+.PHONY: all clean distclean install uninstall

doc/gtkdoc/cpp-docs.xml

@@ -0,0 +1,38 @@
+<?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'">
+  <!ENTITY server "www.defora.org/doc/html">
+  <!ENTITY title "DeforaOS cpp">
+  <!ENTITY version "0.0.1">
+]>
+<book id="index">
+  <bookinfo>
+    <title>cpp Reference Manual</title>
+    <releaseinfo>
+      for cpp &version;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="http://&server;/cpp/index.html">http://&server;/cpp/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>&title;</title>
+    <xi:include href="xml/common.xml"/>
+    <xi:include href="xml/config.xml"/>
+    <xi:include href="xml/cpp.xml"/>
+    <xi:include href="xml/parser.xml"/>
+
+  </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>

doc/gtkdoc/project.conf

@@ -0,0 +1 @@
+dist=Makefile,cpp-docs.xml

doc/project.conf

@@ -0,0 +1,17 @@
+subdirs=gtkdoc
+targets=gtkdoc/cpp.types,gtkdoc/sgml.stamp,html/index.html
+dist=Makefile,GRAMMAR,gtkdoc.sh
+
+[gtkdoc/cpp.types]
+type=script
+script=./gtkdoc.sh
+
+[gtkdoc/sgml.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc/cpp.types
+
+[html/index.html]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc/cpp-docs.xml,gtkdoc/sgml.stamp