doc: generate documentation with Gtk-Doc
This commit is contained in:
parent
9e28dbeb5a
commit
21ed220507
|
|
@ -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
|
||||
---------------
|
||||
|
||||
|
|
|
|||
290
doc/gtkdoc.sh
Executable file
290
doc/gtkdoc.sh
Executable file
|
|
@ -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
|
||||
44
doc/gtkdoc/Panel-docs.xml
Normal file
44
doc/gtkdoc/Panel-docs.xml
Normal file
|
|
@ -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>
|
||||
50
doc/gtkdoc/Panel-sections.txt
Normal file
50
doc/gtkdoc/Panel-sections.txt
Normal file
|
|
@ -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>
|
||||
|
||||
1
doc/gtkdoc/project.conf
Normal file
1
doc/gtkdoc/project.conf
Normal file
|
|
@ -0,0 +1 @@
|
|||
dist=Makefile,Panel-docs.xml,Panel-sections.txt,xml/gtkdocentities.ent
|
||||
2
doc/gtkdoc/xml/gtkdocentities.ent
Normal file
2
doc/gtkdoc/xml/gtkdocentities.ent
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
<!ENTITY server "www.defora.org/doc/gtk-doc/html">
|
||||
<!ENTITY title "Reference Manual">
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user