Commit 3cd0a7ae authored by Bastien Nocera's avatar Bastien Nocera Committed by Daniel Drake
Browse files

First pass at adding API docs through gtk-doc

Required a bit of mangling.
parent 26aab5dc
AUTOMAKE_OPTIONS = dist-bzip2
SUBDIRS = src data tests pam po
SUBDIRS = src data tests pam doc po
EXTRA_DIST = TODO intltool-extract.in intltool-merge.in intltool-update.in
......@@ -2,7 +2,9 @@
aclocal || exit 1
autoheader || exit 1
glib-gettextize -f -c || exit 1
gtkdocize --copy || exit 1
intltoolize -c -f || exit 1
libtoolize -c || exit 1
autoconf || exit 1
automake -a -c || exit 1
./configure $*
......@@ -4,6 +4,7 @@ AC_CONFIG_SRCDIR([src/main.c])
AC_CONFIG_HEADERS([config.h])
AC_PREREQ([2.50])
AC_PROG_LIBTOOL
AC_PROG_CC
AM_PROG_CC_C_O
......@@ -47,6 +48,9 @@ AC_MSG_RESULT([$has_pam])
AC_CHECK_PROG([POLKIT_POLICY_FILE_VALIDATE],
[polkit-policy-file-validate], [polkit-policy-file-validate])
AC_PATH_PROG([XSLTPROC], [xsltproc])
GTK_DOC_CHECK([1.3])
AS_AC_EXPAND(DATADIR, $datadir)
DBUS_SERVICES_DIR="$DATADIR/dbus-1/services"
......@@ -57,6 +61,14 @@ AC_DEFINE_UNQUOTED(SYSCONFDIR, "$sysconfdir", [Where the configuration file will
GNOME_COMPILE_WARNINGS
AC_CONFIG_FILES([Makefile] [src/Makefile] [data/Makefile] [tests/Makefile] [pam/Makefile] [po/Makefile.in])
AC_OUTPUT
AC_OUTPUT([
Makefile
src/Makefile
data/Makefile
tests/Makefile
pam/Makefile
doc/Makefile
doc/version.xml
doc/dbus/Makefile
po/Makefile.in
])
SUBDIRS = dbus
NULL =
AUTOMAKE_OPTIONS = 1.7
# The name of the module.
DOC_MODULE=fprintd
# The top-level SGML file.
DOC_MAIN_SGML_FILE=fprintd-docs.xml
# Extra options to supply to gtkdoc-scan
SCAN_OPTIONS=--ignore-headers=config.h
# The directory containing the source code. Relative to $(srcdir)
DOC_SOURCE_DIR=../src
# Used for dependencies
HFILE_GLOB=
#$(top_srcdir)/policy/*.h
CFILE_GLOB=
#$(top_srcdir)/policy/*.c
# Headers to ignore
IGNORE_HFILES= \
$(NULL)
# CFLAGS and LDFLAGS for compiling scan program. Only needed
# if $(DOC_MODULE).types is non-empty.
INCLUDES = \
$(GLIB_CFLAGS) \
-I$(top_srcdir)/src \
$(NULL)
GTKDOC_LIBS = \
$(GLIB_LIBS) \
$(top_builddir)/src/libfprintd.la \
$(NULL)
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS=--sgml-mode --output-format=xml
# Extra options to supply to gtkdoc-mktmpl
MKTMPL_OPTIONS=
# Non-autogenerated SGML files to be included in $(DOC_MAIN_SGML_FILE)
content_files = \
version.xml \
dbus/net.reactivated.Fprint.Manager.ref.xml \
dbus/net.reactivated.Fprint.Device.ref.xml \
$(NULL)
# Images to copy into HTML directory
HTML_IMAGES = \
$(NULL)
# Extra options to supply to gtkdoc-fixref
FIXXREF_OPTIONS=
MAINTAINERCLEANFILES = \
*~ \
Makefile.in \
fprintd.types \
fprintd-*.txt \
$(NULL)
if ENABLE_GTK_DOC
include $(top_srcdir)/gtk-doc.make
else
EXTRA_DIST =
endif
# Version information for marking the documentation
EXTRA_DIST += version.xml.in
all : net.reactivated.Fprint.Manager.ref.xml net.reactivated.Fprint.Device.ref.xml
net.reactivated.Fprint.Manager.ref.xml : $(top_srcdir)/src/manager.xml $(top_srcdir)/doc/dbus/spec-to-docbook.xsl
echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@
$(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@
net.reactivated.Fprint.Device.ref.xml : $(top_srcdir)/src/device.xml $(top_srcdir)/doc/dbus/spec-to-docbook.xsl
echo "<?xml version=\"1.0\"?>""<!DOCTYPE refentry PUBLIC \"-//OASIS//DTD DocBook XML V4.1.2//EN\" \"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd\">" > $@
$(XSLTPROC) $(top_srcdir)/doc/dbus/spec-to-docbook.xsl $< | tail -n +2 >> $@
EXTRA_DIST = spec-to-docbook.xsl dbus-introspect-docs.dtd
clean-local :
rm -f *~ *.ref.xml
<!-- DTD for D-Bus Introspection Documentation -->
<!ELEMENT doc (summary?,description?,errors?,permission?,since?,deprecated,seealso?)>
<!ELEMENT summary (#PCDATA|ref)*>
<!ELEMENT description (#PCDATA|para|example)*>
<!ELEMENT errors (error)*>
<!ELEMENT permission (#PCDATA|ref|para)*>
<!ELEMENT since EMPTY>
<!ATTLIST since version CDATA #REQUIRED>
<!ELEMENT deprecated (#PCDATA|ref)>
<!ATTLIST deprecated version CDATA #REQUIRED>
<!ATTLIST deprecated instead CDATA #REQUIRED>
<!ELEMENT seealso (ref+)>
<!ELEMENT error (#PCDATA|para)*>
<!ATTLIST error name CDATA #REQUIRED>
<!ELEMENT para (#PCDATA|example|code|list|ref)*>
<!ELEMENT example (#PCDATA|para|code|ref)*>
<!ATTLIST language (c|glib|python|shell) #REQUIRED>
<!ATTLIST title CDATA #IMPLIED>
<!ELEMENT list (item*)>
<!ATTLIST list type (bullet|number) #REQUIRED>
<!ELEMENT item (term|definition)*>
<!ELEMENT term (#PCDATA|ref)*>
<!ELEMENT definition (#PCDATA|para)*>
<!ELEMENT code (#PCDATA)>
<!ATTLIST code lang CDATA #IMPLIED>
<!ELEMENT ref CDATA>
<!ATTLIST ref type (parameter|arg|signal|method|interface) #REQUIRED>
<!ATTLIST ref to CDATA #REQUIRED>
<?xml version='1.0'?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
xmlns:doc="http://www.freedesktop.org/dbus/1.0/doc.dtd"
exclude-result-prefixes="doc">
<!--
Convert D-Bus Glib xml into DocBook refentries
Copyright (C) 2007 William Jon McCann
License: GPL
-->
<xsl:output method="xml" indent="yes" encoding="UTF-8"/>
<xsl:template match="/">
<xsl:variable name="interface" select="//interface/@name"/>
<xsl:variable name="basename">
<xsl:call-template name="interface-basename">
<xsl:with-param name="str" select="$interface"/>
</xsl:call-template>
</xsl:variable>
<refentry><xsl:attribute name="id"><xsl:value-of select="$basename"/></xsl:attribute>
<refmeta>
<refentrytitle role="top_of_page"><xsl:value-of select="//interface/@name"/></refentrytitle>
</refmeta>
<refnamediv>
<refname><xsl:value-of select="//interface/@name"/></refname>
<refpurpose><xsl:value-of select="$basename"/> interface</refpurpose>
</refnamediv>
<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Methods</title>
<synopsis>
<xsl:call-template name="methods-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsynopsisdiv>
<xsl:choose>
<xsl:when test="count(///signal) > 0">
<refsect1 role="signal_proto">
<title role="signal_proto.title">Signals</title>
<synopsis>
<xsl:call-template name="signals-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsect1>
</xsl:when>
</xsl:choose>
<refsect1 role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
Objects implementing <xsl:value-of select="$interface"/> also implements
org.freedesktop.DBus.Introspectable,
org.freedesktop.DBus.Properties
</para>
</refsect1>
<xsl:choose>
<xsl:when test="count(///property) > 0">
<refsect1 role="properties">
<title role="properties.title">Properties</title>
<synopsis>
<xsl:call-template name="properties-synopsis">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</synopsis>
</refsect1>
</xsl:when>
</xsl:choose>
<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
<xsl:apply-templates select="//interface/doc:doc"/>
</para>
</refsect1>
<refsect1 role="details">
<title role="details.title">Details</title>
<xsl:call-template name="method-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
<xsl:choose>
<xsl:when test="count(///signal) > 0">
<refsect1 role="signals">
<title role="signals.title">Signal Details</title>
<xsl:call-template name="signal-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="count(///property) > 0">
<refsect1 role="property_details">
<title role="property_details.title">Property Details</title>
<xsl:call-template name="property-details">
<xsl:with-param name="basename" select="$basename"/>
</xsl:call-template>
</refsect1>
</xsl:when>
</xsl:choose>
</refentry>
</xsl:template>
<xsl:template name="property-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:apply-templates select="doc:doc/doc:permission"/>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="property-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///property">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute></anchor>The "<xsl:value-of select="@name"/>" property</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting>'<xsl:value-of select="@name"/>'<xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="2"/></xsl:call-template>
<xsl:call-template name="property-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/></xsl:call-template></programlisting>
</refsect2>
<xsl:call-template name="property-doc"/>
</xsl:for-each>
</xsl:template>
<xsl:template name="signal-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:value-of select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:apply-templates select="doc:doc/doc:permission"/>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="signal-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///signal">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>::<xsl:value-of select="@name"/></xsl:attribute></anchor>The <xsl:value-of select="@name"/> signal</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="signal-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
</refsect2>
<xsl:call-template name="signal-doc"/>
</xsl:for-each>
</xsl:template>
<xsl:template match="doc:code">
<programlisting>
<xsl:apply-templates />
</programlisting>
</xsl:template>
<xsl:template match="doc:tt">
<literal>
<xsl:apply-templates />
</literal>
</xsl:template>
<xsl:template match="doc:i">
<emphasis>
<xsl:apply-templates />
</emphasis>
</xsl:template>
<xsl:template match="doc:b">
<emphasis role="bold">
<xsl:apply-templates />
</emphasis>
</xsl:template>
<xsl:template match="doc:ulink">
<ulink>
<xsl:attribute name="url"><xsl:value-of select="@url"/></xsl:attribute>
<xsl:value-of select="."/>
</ulink>
</xsl:template>
<xsl:template match="doc:summary">
<xsl:apply-templates />
</xsl:template>
<xsl:template match="doc:example">
<informalexample>
<xsl:apply-templates />
</informalexample>
</xsl:template>
<xsl:template name="listitems-do-term">
<xsl:param name="str"/>
<xsl:choose>
<xsl:when test="string-length($str) > 0">
<emphasis role="bold"><xsl:value-of select="$str"/>: </emphasis>
</xsl:when>
</xsl:choose>
</xsl:template>
<xsl:template name="do-listitems">
<xsl:for-each select="doc:item">
<listitem>
<xsl:call-template name="listitems-do-term"><xsl:with-param name="str" select="doc:term"/></xsl:call-template>
<xsl:apply-templates select="doc:definition"/>
</listitem>
</xsl:for-each>
</xsl:template>
<xsl:template match="doc:list">
<para>
<xsl:choose>
<xsl:when test="contains(@type,'number')">
<orderedlist>
<xsl:call-template name="do-listitems"/>
</orderedlist>
</xsl:when>
<xsl:otherwise>
<itemizedlist>
<xsl:call-template name="do-listitems"/>
</itemizedlist>
</xsl:otherwise>
</xsl:choose>
</para>
</xsl:template>
<xsl:template match="doc:para">
<para>
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:description">
<xsl:apply-templates />
</xsl:template>
<xsl:template match="doc:since">
<para role="since">Since <xsl:value-of select="@version"/>
</para>
</xsl:template>
<xsl:template match="doc:deprecated">
<xsl:variable name="name" select="../../@name"/>
<xsl:variable name="parent">
<xsl:call-template name="interface-basename">
<xsl:with-param name="str" select="../../../@name"/>/>
</xsl:call-template>
</xsl:variable>
<xsl:variable name="type" select="name(../..)"/>
<para role="deprecated">
<warning><para><literal><xsl:value-of select="$name"/></literal> is deprecated since version <xsl:value-of select="@version"/> and should not be used in newly-written code. Use
<xsl:variable name="to">
<xsl:choose>
<xsl:when test="contains($type,'property')">
<xsl:value-of select="$parent"/>:<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'signal')">
<xsl:value-of select="$parent"/>::<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'method')">
<xsl:value-of select="$parent"/>.<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:when test="contains($type,'interface')">
<xsl:value-of select="@instead"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@instead"/>
</xsl:otherwise>
</xsl:choose>
</xsl:variable>
<xsl:call-template name="create-link">
<xsl:with-param name="type" select="$type"/>
<xsl:with-param name="to" select="$to"/>
<xsl:with-param name="val" select="@instead"/>
</xsl:call-template>
instead.</para></warning>
</para>
</xsl:template>
<xsl:template match="doc:permission">
<para role="permission">
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:errors">
<para role="errors">
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template match="doc:seealso">
<para>
See also:
<xsl:apply-templates />
</para>
</xsl:template>
<xsl:template name="create-link">
<xsl:param name="type"/>
<xsl:param name="to"/>
<xsl:param name="val"/>
<xsl:choose>
<xsl:when test="contains($type,'property')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
</xsl:when>
<xsl:when test="contains($type,'signal')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><literal><xsl:value-of select="$val"/></literal></link>
</xsl:when>
<xsl:when test="contains($type,'method')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><function><xsl:value-of select="$val"/></function></link>
</xsl:when>
<xsl:when test="contains($type,'interface')">
<link><xsl:attribute name="linkend"><xsl:value-of select="$to"/></xsl:attribute><xsl:value-of select="$val"/></link>
</xsl:when>
</xsl:choose>
</xsl:template>
<xsl:template match="doc:ref">
<xsl:call-template name="create-link">
<xsl:with-param name="type" select="@type"/>
<xsl:with-param name="to" select="@to"/>
<xsl:with-param name="val" select="."/>
</xsl:call-template>
</xsl:template>
<xsl:template name="method-doc">
<xsl:apply-templates select="doc:doc/doc:description"/>
<variablelist role="params">
<xsl:for-each select="arg">
<varlistentry><term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:apply-templates select="doc:doc/doc:summary"/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
<xsl:apply-templates select="doc:doc/doc:since"/>
<xsl:apply-templates select="doc:doc/doc:deprecated"/>
<xsl:choose>
<xsl:when test="count(doc:doc/doc:errors) > 0">
<refsect3>
<title>Errors</title>
<variablelist role="errors">
<xsl:for-each select="doc:doc/doc:errors/doc:error">
<varlistentry>
<term><parameter><xsl:value-of select="@name"/></parameter>:</term>
<listitem><simpara><xsl:apply-templates select="."/></simpara></listitem>
</varlistentry>
</xsl:for-each>
</variablelist>
</refsect3>
</xsl:when>
</xsl:choose>
<xsl:choose>
<xsl:when test="count(doc:doc/doc:permission) > 0">
<refsect3>
<title>Permissions</title>
<xsl:apply-templates select="doc:doc/doc:permission"/>
</refsect3>
</xsl:when>
</xsl:choose>
<xsl:apply-templates select="doc:doc/doc:seealso"/>
</xsl:template>
<xsl:template name="method-details">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///method">
<refsect2>
<title><anchor role="function"><xsl:attribute name="id"><xsl:value-of select="$basename"/>.<xsl:value-of select="@name"/></xsl:attribute></anchor><xsl:value-of select="@name"/> ()</title>
<indexterm><primary><xsl:value-of select="@name"/></primary><secondary><xsl:value-of select="$basename"/></secondary></indexterm>
<programlisting><xsl:value-of select="@name"/> (<xsl:call-template name="method-args"><xsl:with-param name="indent" select="string-length(@name) + 2"/><xsl:with-param name="prefix" select="."/></xsl:call-template>)</programlisting>
</refsect2>
<xsl:call-template name="method-doc"/>
</xsl:for-each>
</xsl:template>
<xsl:template name="properties-synopsis">
<xsl:param name="basename"/>
<xsl:variable name="longest">
<xsl:call-template name="find-longest">
<xsl:with-param name="set" select="///property/@name"/>
</xsl:call-template>
</xsl:variable>
<xsl:for-each select="///property">
<link><xsl:attribute name="linkend"><xsl:value-of select="$basename"/>:<xsl:value-of select="@name"/></xsl:attribute>'<xsl:value-of select="@name"/>'</link><xsl:call-template name="pad-spaces"><xsl:with-param name="width" select="$longest - string-length(@name) + 1"/></xsl:call-template> <xsl:call-template name="property-args"><xsl:with-param name="indent" select="$longest + 2"/></xsl:call-template>
</xsl:for-each>
</xsl:template>
<xsl:template name="signals-synopsis">