diff --git a/README.md b/README.md index 9ca44da..5403e7e 100644 --- a/README.md +++ b/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 --------------- diff --git a/doc/gtkdoc.sh b/doc/gtkdoc.sh new file mode 100755 index 0000000..6dc5b32 --- /dev/null +++ b/doc/gtkdoc.sh @@ -0,0 +1,290 @@ +#!/bin/sh +#$Id$ +#Copyright (c) 2012-2020 Pierre Pronchery +# +#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 diff --git a/doc/gtkdoc/Panel-docs.xml b/doc/gtkdoc/Panel-docs.xml new file mode 100644 index 0000000..16a30cb --- /dev/null +++ b/doc/gtkdoc/Panel-docs.xml @@ -0,0 +1,44 @@ + + + + %gtkdocentities; + + %configentities; +]> + + + &vendor; &package; &title; + + for &vendor; &package; &version;. + The latest version of this documentation can be found on-line at + https://&server;/&package;/. + + + + + &vendor; &package; + + + + + + + API Index + + + + Index of deprecated API + + + + diff --git a/doc/gtkdoc/Panel-sections.txt b/doc/gtkdoc/Panel-sections.txt new file mode 100644 index 0000000..8b28c8b --- /dev/null +++ b/doc/gtkdoc/Panel-sections.txt @@ -0,0 +1,50 @@ +
+Panel + +
+ +
+applet +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 +
+ +
+panel +PanelPosition +PANEL_POSITION_LAST +PANEL_POSITION_COUNT +PANEL_POSITION_DEFAULT +PanelMessage +PanelMessageShow +PANEL_CLIENT_MESSAGE +Panel +
+ +
+window +PanelWindowType +panel_window_get_icon_size +panel_window_get_orientation + +PanelWindow +panel_window_get_type +
+ diff --git a/doc/gtkdoc/project.conf b/doc/gtkdoc/project.conf new file mode 100644 index 0000000..6b710ec --- /dev/null +++ b/doc/gtkdoc/project.conf @@ -0,0 +1 @@ +dist=Makefile,Panel-docs.xml,Panel-sections.txt,xml/gtkdocentities.ent diff --git a/doc/gtkdoc/xml/gtkdocentities.ent b/doc/gtkdoc/xml/gtkdocentities.ent new file mode 100644 index 0000000..db0b85f --- /dev/null +++ b/doc/gtkdoc/xml/gtkdocentities.ent @@ -0,0 +1,2 @@ + + diff --git a/doc/project.conf b/doc/project.conf index 95ca551..e30829c 100644 --- a/doc/project.conf +++ b/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 -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 +subdirs=gtkdoc +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 diff --git a/project.conf b/project.conf index 4a000de..5026ab6 100644 --- a/project.conf +++ b/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