Generate documentation with GtkDoc for DeforaOS Browser

doc/gtkdoc.sh

@@ -0,0 +1,223 @@
+#!/bin/sh
+#$Id$
+#Copyright (c) 2012-2017 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.
+
+
+
+#variables
+PREFIX="/usr/local"
+PROGNAME="gtkdoc.sh"
+#executables
+CP="cp"
+DEBUG="_debug"
+GTKDOC_FIXXREF="gtkdoc-fixxref"
+GTKDOC_MKDB="gtkdoc-mkdb"
+GTKDOC_MKHTML="gtkdoc-mkhtml"
+GTKDOC_MKTMPL="gtkdoc-mktmpl"
+GTKDOC_SCAN="gtkdoc-scan"
+INSTALL="install -m 0644"
+MKDIR="mkdir -m 0755 -p"
+RM="rm -f"
+TOUCH="touch"
+
+[ -f "../config.sh" ] && . "../config.sh"
+
+
+#functions
+#debug
+_debug()
+{
+	echo "$@" 1>&3
+	"$@"
+}
+
+
+#error
+_error()
+{
+	echo "$PROGNAME: $@" 1>&2
+	return 2
+}
+
+
+#usage
+_usage()
+{
+	echo "Usage: $PROGNAME [-c|-i|-u][-P prefix] target..." 1>&2
+	return 1
+}
+
+
+#main
+clean=0
+install=0
+uninstall=0
+while getopts "ciO:uP:" name; do
+	case "$name" in
+		c)
+			clean=1
+			;;
+		i)
+			uninstall=0
+			install=1
+			;;
+		O)
+			export "${OPTARG%%=*}"="${OPTARG#*=}"
+			;;
+		u)
+			install=0
+			uninstall=1
+			;;
+		P)
+			PREFIX="$OPTARG"
+			;;
+		?)
+			_usage
+			exit $?
+			;;
+	esac
+done
+shift $((OPTIND - 1))
+if [ $# -lt 1 ]; then
+	_usage
+	exit $?
+fi
+
+#check the variables
+if [ -z "$PACKAGE" ]; then
+	_error "The PACKAGE variable needs to be set"
+	exit $?
+fi
+MODULE="$PACKAGE"
+
+[ -z "$DATADIR" ] && DATADIR="$PREFIX/share"
+instdir="$DATADIR/gtk-doc/html"
+
+exec 3>&1
+while [ $# -gt 0 ]; do
+	target="$1"
+	target="${target#$OBJDIR}"
+	shift
+
+	#clean
+	[ "$clean" -ne 0 ] && continue
+
+	#uninstall
+	if [ "$uninstall" -eq 1 ]; then
+		for i in "${OBJDIR}gtkdoc/html/"*.*; do
+			[ -f "$i" ] || continue
+			file="${i##*/}"
+			$DEBUG $RM -- "$instdir/$MODULE/$file"	|| exit 2
+		done
+		continue
+	fi
+
+	#create
+	case "$target" in
+		gtkdoc/html.stamp)
+			driver="../$MODULE-docs.xml"
+			if [ -n "$OBJDIR" ]; then
+				driver="gtkdoc/$MODULE-docs.xml"
+				$DEBUG $CP -- "$driver" "${OBJDIR}gtkdoc" \
+								|| exit 2
+			fi
+			output="${OBJDIR}gtkdoc/html"
+			$DEBUG $MKDIR -- "$output"		|| exit 2
+			(cd "$output" &&
+				$DEBUG $GTKDOC_MKHTML "$MODULE" \
+					"${OBJDIR}$driver")
+			#detect when gtk-doc is not available
+			res=$?
+			if [ $res -eq 127 ]; then
+				_error "$GTKDOC_MKHTML: Not available" \
+					"(not generating documentation)"
+				continue
+			elif [ $res -ne 0 ]; then
+				exit 2
+			fi
+			output="${OBJDIR}gtkdoc"
+			(cd "$output" &&
+				$DEBUG $GTKDOC_FIXXREF \
+					--module="$MODULE" \
+					--module-dir="html" \
+					--html-dir="$instdir")	|| exit 2
+			;;
+		gtkdoc/sgml.stamp)
+			output="xml"
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc/xml"
+				$DEBUG $MKDIR -- "$output"	|| exit 2
+			fi
+			(cd "${OBJDIR}gtkdoc" &&
+				$DEBUG $GTKDOC_MKDB \
+					--module="$MODULE" \
+					--output-dir="$output" \
+					--output-format="xml" \
+					--tmpl-dir="tmpl")
+			;;
+		gtkdoc/tmpl.stamp)
+			output="tmpl"
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc/tmpl"
+				$DEBUG $MKDIR -- "$output"	|| exit 2
+			fi
+			(cd "${OBJDIR}gtkdoc" &&
+				$DEBUG $GTKDOC_MKTMPL \
+					--module="$MODULE" \
+					--output-dir="$output")
+			;;
+		gtkdoc/*.types)
+			output="doc/gtkdoc"			|| exit 2
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc"
+				$DEBUG $MKDIR -- "$output"	|| exit 2
+			fi
+			(cd ".." &&
+				$DEBUG $GTKDOC_SCAN \
+					--module="$MODULE" \
+					--source-dir="include" \
+					--output-dir="$output")
+			;;
+		*)
+			_error "$target: Unknown type"
+			exit $?
+			;;
+	esac
+	#XXX ignore errors
+	if [ $? -ne 0 ]; then
+		_error "$target: Could not create documentation"
+		install=0
+	fi
+	$TOUCH "$target"
+
+	#install
+	if [ "$install" -eq 1 ]; then
+		$DEBUG $MKDIR "$instdir/$MODULE"		|| exit 2
+		for i in "${OBJDIR}gtkdoc/html/"*.*; do
+			[ -f "$i" ] || continue
+			file="${i##*/}"
+			$DEBUG $INSTALL "$i" "$instdir/$MODULE/$file" \
+								|| exit 2
+		done
+	fi
+done

doc/gtkdoc/Browser-docs.xml

@@ -0,0 +1,34 @@
+<?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/gtk-doc/html">
+  <!ENTITY title "DeforaOS Browser">
+  <!ENTITY version "0.5.3">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>Browser Reference Manual</title>
+    <releaseinfo>
+      for Browser &version;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://&server;/Browser/index.html">https://&server;/Browser/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>&title;</title>
+    <xi:include href="xml/desktop.xml"/>
+    <xi:include href="xml/plugin.xml"/>
+    <xi:include href="xml/vfs.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>
+</book>

doc/gtkdoc/project.conf

@@ -0,0 +1,2 @@
+subdirs=tmpl
+dist=Makefile,Browser-docs.xml

doc/gtkdoc/tmpl/Browser.tmpl

@@ -0,0 +1,22 @@
+<!-- ##### SECTION Title ##### -->
+Browser
+
+<!-- ##### SECTION Short_Description ##### -->
+DeforaOS Desktop Browser
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+File manager and image browser for the DeforaOS desktop.
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+DeforaOS libDesktop, DeforaOS libSystem
+</para>
+
+<!-- ##### SECTION Stability_Level ##### -->
+
+
+<!-- ##### SECTION Image ##### -->
+
+

doc/gtkdoc/tmpl/project.conf

@@ -0,0 +1 @@
+dist=Makefile,Browser.sgml

doc/project.conf

@@ -1,4 +1,5 @@
-targets=browser.1,browser.html,browser.xml,copy.1,copy.html,copy.xml,delete.1,delete.html,delete.xml,desktop.1,desktop.html,desktop.xml,desktopctl.1,desktopctl.html,desktopctl.xml,move.1,move.html,move.xml,open.1,open.html,open.xml,pinentry-sudo-askpass,properties.1,properties.html,properties.xml,view.1,view.html,view.xml,zenity-sudo-askpass
+subdirs=gtkdoc
+targets=browser.1,browser.html,browser.xml,copy.1,copy.html,copy.xml,delete.1,delete.html,delete.xml,desktop.1,desktop.html,desktop.xml,desktopctl.1,desktopctl.html,desktopctl.xml,gtkdoc/Browser.types,gtkdoc/tmpl.stamp,gtkdoc/sgml.stamp,gtkdoc/html.stamp,move.1,move.html,move.xml,open.1,open.html,open.xml,pinentry-sudo-askpass,properties.1,properties.html,properties.xml,view.1,view.html,view.xml,zenity-sudo-askpass
 dist=Makefile,browser.css.xml,browser.xml.in,copy.css.xml,copy.xml.in,delete.css.xml,delete.xml.in,desktop.css.xml,desktop.xml.in,desktopctl.css.xml,desktopctl.xml.in,docbook.sh,manual.css.xml,mime.conf,move.css.xml,move.xml.in,open.css.xml,open.xml.in,pinentry-sudo-askpass.in,properties.css.xml,properties.xml.in,view.css.xml,view.xml.in,zenity-sudo-askpass.in
 
 [browser.1]
@@ -86,6 +87,27 @@ type=script
 script=../tools/subst.sh
 depends=desktopctl.xml.in
 
+[gtkdoc/Browser.types]
+type=script
+script=./gtkdoc.sh
+depends=../config.sh
+
+[gtkdoc/tmpl.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,gtkdoc/Browser.types
+
+[gtkdoc/sgml.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,gtkdoc/tmpl.stamp
+
+[gtkdoc/html.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,gtkdoc/Browser-docs.xml,gtkdoc/sgml.stamp
+install=
+
 [move.1]
 type=script
 script=./docbook.sh