doc: generate documentation with Gtk-Doc

README.md

@@ -52,6 +52,9 @@ Manual pages for each of the executables installed are available in the `doc`
 folder. They are written in the DocBook-XML format, and need libxslt and
 DocBook-XSL to be installed for conversion to the HTML or man file format.
 
+Likewise, the API reference for Panel (applets) is available in the
+`doc/gtkdoc` folder, and is generated using gtk-doc.
+
 Extending Panel
 ---------------
 

doc/gtkdoc.sh

@@ -0,0 +1,290 @@
+#!/bin/sh
+#$Id$
+#Copyright (c) 2012-2020 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
+CONFIGSH="${0%/gtkdoc.sh}/../config.sh"
+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"
+RMDIR="rmdir"
+TOUCH="touch"
+
+[ -f "$CONFIGSH" ] && . "$CONFIGSH"
+
+
+#functions
+#debug
+_debug()
+{
+	echo "$@" 1>&3
+	"$@"
+}
+
+
+#error
+_error()
+{
+	echo "$PROGNAME: $@" 1>&2
+	return 2
+}
+
+
+#gtkdoc_fixxref
+_gtkdoc_fixxref()
+{
+	module="$1"
+	moduledir="$2"
+	htmldir="$3"
+	outputdir="$4"
+
+	(cd "$outputdir" &&
+		$DEBUG $GTKDOC_FIXXREF \
+				--module="$module" \
+				--module-dir="$moduledir" \
+				--html-dir="$htmldir")	|| exit 2
+}
+
+
+#gtkdoc_mkdb
+_gtkdoc_mkdb()
+{
+	module="$1"
+	sourcedir="$2"
+	outputdir="$3"
+
+	(cd "$sourcedir" &&
+		$DEBUG $GTKDOC_MKDB --module="$module" \
+				--output-dir="$outputdir" \
+				--output-format="xml" --tmpl-dir="tmpl")
+}
+
+
+#gtkdoc_mkhtml
+_gtkdoc_mkhtml()
+{
+	module="$1"
+	path="$2"
+	driver="$3"
+	outputdir="$4"
+
+	(cd "$outputdir" &&
+		$DEBUG $GTKDOC_MKHTML --path "$path" "$module" "$driver")
+}
+
+
+#gtkdoc_mktmpl
+_gtkdoc_mktmpl()
+{
+	module="$1"
+	sourcedir="$2"
+	outputdir="$3"
+
+	(cd "$sourcedir" &&
+		$DEBUG $GTKDOC_MKTMPL --module="$module" \
+				--output-dir="$outputdir")
+}
+
+
+#gtkdoc_scan
+_gtkdoc_scan()
+{
+	module="$1"
+	sourcedir="$2"
+	outputdir="$3"
+
+	(cd ".." &&
+		$DEBUG $GTKDOC_SCAN --module="$module" \
+				--source-dir="$sourcedir" \
+				--output-dir="$outputdir")
+#		--rebuild-types
+}
+
+
+#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
+		if [ -d "$instdir/$MODULE" ]; then
+			$DEBUG $RMDIR -- "$instdir/$MODULE"	|| exit 2
+		fi
+		continue
+	fi
+
+	#create
+	case "$target" in
+		gtkdoc/html.stamp)
+			output="${OBJDIR}gtkdoc/html"
+			$DEBUG $MKDIR -- "$output"		|| exit 2
+			driver="$MODULE-docs.xml"
+			oldpath="$PWD"
+			[ -n "$OBJDIR" ] && for file in \
+				"gtkdoc/$driver" \
+				"gtkdoc/xml/gtkdocentities.ent"; do
+				[ -f "$file" ] || continue
+				$DEBUG $CP -- "$file" \
+						"${OBJDIR}$file" || exit 2
+			done
+			_gtkdoc_mkhtml "$MODULE" "${oldpath%/*}" "../$driver" \
+					"$output"
+			#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"
+			_gtkdoc_fixxref "$MODULE" "html" "$instdir" "$output"
+			;;
+		gtkdoc/tmpl.stamp)
+			output="tmpl"
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc/tmpl"
+				$DEBUG $MKDIR -- "$output"	|| exit 2
+			fi
+			_gtkdoc_mktmpl "$MODULE" "${OBJDIR}gtkdoc" "$output"
+			;;
+		gtkdoc/xml.stamp)
+			output="xml"
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc"
+				sections="gtkdoc/$MODULE-sections.txt"
+				$DEBUG $MKDIR -- "$output/xml"	|| exit 2
+				$DEBUG $CP -- "$sections" "$output" \
+								|| exit 2
+				_gtkdoc_scan "$MODULE" "include" "$output"
+				output="${OBJDIR}gtkdoc/xml"
+			fi
+			_gtkdoc_mkdb "$MODULE" "${OBJDIR}gtkdoc" "$output"
+			;;
+		gtkdoc/*.types)
+			output="$PWD/gtkdoc"			|| exit 2
+			if [ -n "$OBJDIR" ]; then
+				output="${OBJDIR}gtkdoc"
+				$DEBUG $MKDIR -- "$output"	|| exit 2
+			fi
+			_gtkdoc_scan "$MODULE" "include" "$output"
+			;;
+		*)
+			_error "$target: Unknown type"
+			exit $?
+			;;
+	esac
+	#XXX ignore errors
+	if [ $? -ne 0 ]; then
+		_error "$target: Could not create documentation"
+		install=0
+	fi
+	$TOUCH "${OBJDIR}$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/Panel-docs.xml

@@ -0,0 +1,44 @@
+<?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 % gtkdocentities SYSTEM "xml/gtkdocentities.ent">
+  %gtkdocentities;
+  <!ENTITY % configentities SYSTEM "config.ent">
+  %configentities;
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>&vendor; &package; &title;</title>
+    <releaseinfo>
+      for &vendor; &package; &version;.
+      The latest version of this documentation can be found on-line at
+      <ulink role="online-location" url="https://&server;/&package;/">https://&server;/&package;/</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter>
+    <title>&vendor; &package;</title>
+    <xi:include href="xml/panel.xml"/>
+    <xi:include href="xml/window.xml"/>
+    <xi:include href="xml/applet.xml"/>
+  </chapter>
+  <!-- enable this when you use gobject types
+  <chapter id="object-tree">
+    <title>Object Hierarchy</title>
+    <xi:include href="xml/tree_index.sgml"/>
+  </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>
+  <!-- enable this when you use gobject introspection annotations
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+  -->
+</book>

doc/gtkdoc/Panel-sections.txt

@@ -0,0 +1,50 @@
+<SECTION>
+<FILE>Panel</FILE>
+
+</SECTION>
+
+<SECTION>
+<FILE>applet</FILE>
+config_get
+config_set
+error
+about_dialog
+lock
+lock_dialog
+logout
+logout_dialog
+position_menu
+preferences_dialog
+rotate_screen
+shutdown
+shutdown_dialog
+suspend
+suspend_dialog
+init
+destroy
+settings
+PanelApplet
+</SECTION>
+
+<SECTION>
+<FILE>panel</FILE>
+PanelPosition
+PANEL_POSITION_LAST
+PANEL_POSITION_COUNT
+PANEL_POSITION_DEFAULT
+PanelMessage
+PanelMessageShow
+PANEL_CLIENT_MESSAGE
+Panel
+</SECTION>
+
+<SECTION>
+<FILE>window</FILE>
+PanelWindowType
+panel_window_get_icon_size
+panel_window_get_orientation
+<SUBSECTION Standard>
+PanelWindow
+panel_window_get_type
+</SECTION>
+

doc/gtkdoc/project.conf

@@ -0,0 +1 @@
+dist=Makefile,Panel-docs.xml,Panel-sections.txt,xml/gtkdocentities.ent

doc/gtkdoc/xml/gtkdocentities.ent

@@ -0,0 +1,2 @@
+<!ENTITY server "www.defora.org/doc/gtk-doc/html">
+<!ENTITY title "Reference Manual">

doc/project.conf

@@ -1,7 +1,29 @@
-targets=panel.1,panel.html,panel.xml,panelctl.1,panelctl.html,panelctl.xml,panel-embed.1,panel-embed.html,panel-embed.xml,panel-message.1,panel-message.html,panel-message.xml,panel-notify.1,panel-notify.html,panel-notify.xml,settings.1,settings.html,settings.xml,wifibrowser.1,wifibrowser.html,wifibrowser.xml
+subdirs=gtkdoc
-dist=Makefile,docbook.sh,manual.css.xml,panel.conf,panel.css.xml,panel.xml.in,panelctl.css.xml,panelctl.xml.in,panel-embed.css.xml,panel-embed.xml.in,panel-message.css.xml,panel-message.xml.in,panel-notify.css.xml,panel-notify.xml.in,settings.css.xml,settings.xml.in,wifibrowser.css.xml,wifibrowser.xml.in,wpa_supplicant.conf
+targets=gtkdoc/Panel.types,gtkdoc/html.stamp,gtkdoc/tmpl.stamp,gtkdoc/xml.stamp,panel.1,panel.html,panel.xml,panelctl.1,panelctl.html,panelctl.xml,panel-embed.1,panel-embed.html,panel-embed.xml,panel-message.1,panel-message.html,panel-message.xml,panel-notify.1,panel-notify.html,panel-notify.xml,settings.1,settings.html,settings.xml,wifibrowser.1,wifibrowser.html,wifibrowser.xml
+dist=Makefile,docbook.sh,gtkdoc.sh,manual.css.xml,panel.conf,panel.css.xml,panel.xml.in,panelctl.css.xml,panelctl.xml.in,panel-embed.css.xml,panel-embed.xml.in,panel-message.css.xml,panel-message.xml.in,panel-notify.css.xml,panel-notify.xml.in,settings.css.xml,settings.xml.in,wifibrowser.css.xml,wifibrowser.xml.in,wpa_supplicant.conf
 
 #targets
+[gtkdoc/Panel.types]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,../config.sh
+
+[gtkdoc/html.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,gtkdoc/Panel-docs.xml,$(OBJDIR)gtkdoc/xml.stamp,gtkdoc/xml/gtkdocentities.ent,../config.ent
+install=
+
+[gtkdoc/tmpl.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,$(OBJDIR)gtkdoc/Panel.types
+
+[gtkdoc/xml.stamp]
+type=script
+script=./gtkdoc.sh
+depends=gtkdoc.sh,$(OBJDIR)gtkdoc/tmpl.stamp
+
 [panel.1]
 type=script
 script=./docbook.sh

project.conf

@@ -1,11 +1,11 @@
 package=Panel
 version=0.4.2
 vendor=Desktop
-config=h,sh
+config=ent,h,sh
 
 subdirs=data,doc,include,po,src,src/applets,tests,tools
 targets=tests
-dist=COPYING,README.md,Makefile,config.h,config.sh
+dist=COPYING,README.md,Makefile,config.ent,config.h,config.sh
 mode=debug
 
 #modes