Update gtk-doc configuration

Disable the template build. Depend on version 1.14 of gtk-doc. Switch to
using XML rather than SGML. Add a gtk-doc check that is executed during
‘make test’. Improve the documentation index page. Add the sections.txt
file and alter it according to the public API symbols.

diff --git a/.gitignore b/.gitignore
index a09b9d4..5023561 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -9,14 +9,15 @@ configure
 config.*
 debian
 depcomp
-docs/reference/html/
-docs/reference/libsignon-glib*
-docs/reference/tmpl/
-docs/reference/xml/
+/docs/reference/html/
+/docs/reference/libsignon-glib*
+!/docs/reference/libsignon-glib-sections.txt
+/docs/reference/tmpl/
+/docs/reference/xml/
 gtk-doc.make
 install-sh
-libsignon-glib/signon-marshal.c
-libsignon-glib/signon-marshal.h
+/libsignon-glib/signon-marshal.c
+/libsignon-glib/signon-marshal.h
 libtool
 ltmain.sh
 m4/gtk-doc.m4

diff --git a/configure.ac b/configure.ac
index db101c6..57fab4a 100644 (file)
--- a/configure.ac
+++ b/configure.ac
@@ -27,7 +27,7 @@ AM_PROG_CC_STDC
 AC_HEADER_STDC
 AC_PROG_LIBTOOL
 
-GTK_DOC_CHECK([1.3])
+GTK_DOC_CHECK([1.14], [--flavour no-tmpl])
 
 AC_ARG_ENABLE(cast-checks,  [  --disable-cast-checks   compile with GLIB cast checks disabled],[cchecks=${enableval}],cchecks=yes)
 if test "x$cchecks" = "xno"; then

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index a2dbb4d..ae5f9c8 100644 (file)
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -12,24 +12,24 @@ AUTOMAKE_OPTIONS = 1.6
 DOC_MODULE=libsignon-glib
 
 # The top-level SGML file. You can change this if you want to.
-DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
 
 # The directory containing the source code. Relative to $(srcdir).
 # gtk-doc will search all .c & .h files beneath here for inline comments
 # documenting the functions and macros.
 # e.g. DOC_SOURCE_DIR=../../../gtk
-DOC_SOURCE_DIR=$(top_srcdir)
+DOC_SOURCE_DIR=$(top_srcdir)/libsignon-glib
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
 SCANGOBJ_OPTIONS=
 
 # Extra options to supply to gtkdoc-scan.
 # e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
-SCAN_OPTIONS=
+SCAN_OPTIONS=--rebuild-types
 
 # Extra options to supply to gtkdoc-mkdb.
 # e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
-MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--source-dir=$(top_srcdir)/libsignon-glib --sgml-mode --output-format=xml --name-space=signon
 
 # Extra options to supply to gtkdoc-fixref. Not normally needed.
 # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
@@ -44,6 +44,9 @@ CFILE_GLOB=$(top_srcdir)/libsignon-glib/*.c
 # Header files to ignore when scanning.
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
 IGNORE_HFILES= \
+       signon-auth-session-client-glib-gen.h \
+       signon-client-glib-gen.h \
+       signon-identity-glib-gen.h \
        signon-dbus-queue.h \
        signon-internals.h \
        signon-proxy.h \
@@ -63,7 +66,7 @@ content_files=
 # signals and properties.
 # e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
 # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-INCLUDES=-I$(top_srcdir) $(DEPS_CFLAGS)
+AM_CPPFLAGS=$(DEPS_CFLAGS)
 GTKDOC_LIBS=$(top_builddir)/libsignon-glib/libsignon-glib.la $(DEPS_LIBS)
 
 # This includes the standard gtk-doc make rules, copied by gtkdocize.
@@ -72,3 +75,7 @@ include $(top_srcdir)/gtk-doc.make
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
 EXTRA_DIST += 
+
+if ENABLE_GTK_DOC
+TESTS = $(GTKDOC_CHECK)
+endif

diff --git a/docs/reference/libsignon-glib-docs.sgml b/docs/reference/libsignon-glib-docs.sgml
deleted file mode 100644 (file)
index 41ee7b4..0000000
--- a/docs/reference/libsignon-glib-docs.sgml
+++ /dev/null
@@ -1,19 +0,0 @@
-<?xml version="1.0"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
-               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
-<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
-  <bookinfo>
-    <title>libsignon-glib Reference Manual</title>
-    <releaseinfo>
-      The latest version of this documentation can be found on-line at
-      <ulink role="online-location" url="http://[SERVER]/libsignon-glib/index.html">http://[SERVER]/libsignon-glib/</ulink>.
-    </releaseinfo>
-  </bookinfo>
-
-  <chapter>
-    <title>libsignon-glib</title>
-    <xi:include href="xml/signon-auth-service.xml"/>
-    <xi:include href="xml/signon-auth-session.xml"/>
-    <xi:include href="xml/signon-identity.xml"/>
-  </chapter>
-</book>

diff --git a/docs/reference/libsignon-glib-docs.xml b/docs/reference/libsignon-glib-docs.xml
new file mode 100644 (file)
index 0000000..1dcd206
--- /dev/null
+++ b/docs/reference/libsignon-glib-docs.xml
@@ -0,0 +1,42 @@
+<?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">
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>libsignon-glib Reference Manual</title>
+    <releaseinfo>
+      The latest version of this documentation can be built from the source code
+      at <ulink role="online-location" url="https://code.google.com/p/accounts-sso/source/checkout?repo=libsignon-glib">https://code.google.com/p/accounts-sso/source/checkout?repo=libsignon-glib</ulink>.
+    </releaseinfo>
+  </bookinfo>
+
+  <chapter id="libsignon-glib">
+    <title>libsignon-glib</title>
+    <para>
+    libsignon-glib provides authorization and authentication management for GLib
+    applications.
+    </para>
+    <xi:include href="xml/signon-auth-service.xml"/>
+    <xi:include href="xml/signon-auth-session.xml"/>
+    <xi:include href="xml/signon-errors.xml"/>
+    <xi:include href="xml/signon-identity.xml"/>
+    <xi:include href="xml/signon-identity-info.xml"/>
+  </chapter>
+
+  <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="api-index-deprecated" role="deprecated">
+    <title>Index of deprecated symbols</title>
+    <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+  </index>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>

diff --git a/docs/reference/libsignon-glib-sections.txt b/docs/reference/libsignon-glib-sections.txt
new file mode 100644 (file)
index 0000000..2c70618
--- /dev/null
+++ b/docs/reference/libsignon-glib-sections.txt
@@ -0,0 +1,133 @@
+<SECTION>
+<FILE>signon-auth-service</FILE>
+<TITLE>SignonAuthService</TITLE>
+SignonQueryMechanismCb
+SignonQueryMethodsCb
+signon_auth_service_new
+signon_auth_service_query_mechanisms
+signon_auth_service_query_methods
+<SUBSECTION Private>
+SignonAuthServiceClass
+SignonAuthServicePrivate
+<SUBSECTION Standard>
+SIGNON_AUTH_SERVICE
+SIGNON_AUTH_SERVICE_CLASS
+SIGNON_AUTH_SERVICE_GET_CLASS
+SIGNON_IS_AUTH_SERVICE
+SIGNON_IS_AUTH_SERVICE_CLASS
+SIGNON_TYPE_AUTH_SERVICE
+signon_auth_service_get_type
+</SECTION>
+
+<SECTION>
+<FILE>signon-auth-session</FILE>
+<TITLE>SignonAuthSession</TITLE>
+SIGNON_SESSION_DATA_CAPTION
+SIGNON_SESSION_DATA_PROXY
+SIGNON_SESSION_DATA_REALM
+SIGNON_SESSION_DATA_RENEW_TOKEN
+SIGNON_SESSION_DATA_SECRET
+SIGNON_SESSION_DATA_TIMEOUT
+SIGNON_SESSION_DATA_UI_POLICY
+SIGNON_SESSION_DATA_USERNAME
+SIGNON_SESSION_DATA_WINDOW_ID
+SignonAuthSession
+SignonAuthSessionProcessCb
+SignonAuthSessionQueryAvailableMechanismsCb
+SignonSessionDataUiPolicy
+signon_auth_session_cancel
+signon_auth_session_get_method
+signon_auth_session_new
+signon_auth_session_process
+signon_auth_session_query_available_mechanisms
+<SUBSECTION Private>
+SignonAuthSessionClass
+SignonAuthSessionPrivate
+<SUBSECTION Standard>
+SIGNON_AUTH_SESSION
+SIGNON_AUTH_SESSION_CLASS
+SIGNON_AUTH_SESSION_GET_CLASS
+SIGNON_IS_AUTH_SESSION
+SIGNON_IS_AUTH_SESSION_CLASS
+SIGNON_TYPE_AUTH_SESSION
+SIGNON_TYPE_SESSION_DATA_UI_POLICY
+signon_auth_session_get_type
+signon_session_data_ui_policy_get_type
+</SECTION>
+
+<SECTION>
+<FILE>signon-errors</FILE>
+SignonError
+<SUBSECTION Private>
+signon_error_quark
+<SUBSECTION Standard>
+SIGNON_ERROR
+SIGNON_TYPE_ERROR
+signon_error_get_type
+</SECTION>
+
+<SECTION>
+<FILE>signon-identity</FILE>
+<TITLE>SignonIdentity</TITLE>
+SignonIdentity
+SignonIdentityInfoCb
+SignonIdentityReferenceAddedCb
+SignonIdentityReferenceRemovedCb
+SignonIdentityRemovedCb
+SignonIdentitySignedOutCb
+SignonIdentityStoreCredentialsCb
+SignonIdentityVerifyCb
+SignonIdentityVoidCb
+signon_identity_add_reference
+signon_identity_create_session
+signon_identity_get_last_error
+signon_identity_new
+signon_identity_new_from_db
+signon_identity_query_info
+signon_identity_remove
+signon_identity_remove_reference
+signon_identity_signout
+signon_identity_store_credentials_with_args
+signon_identity_store_credentials_with_info
+signon_identity_verify_secret
+<SUBSECTION Private>
+SignonIdentityClass
+SignonIdentityPrivate
+<SUBSECTION Standard>
+SIGNON_IDENTITY
+SIGNON_IDENTITY_CLASS
+SIGNON_IDENTITY_GET_CLASS
+SIGNON_IS_IDENTITY
+SIGNON_IS_IDENTITY_CLASS
+SIGNON_TYPE_IDENTITY
+signon_identity_get_type
+</SECTION>
+
+<SECTION>
+<FILE>signon-identity-info</FILE>
+SignonIdentityInfo
+SignonIdentityType
+signon_identity_info_copy
+signon_identity_info_free
+signon_identity_info_get_access_control_list
+signon_identity_info_get_caption
+signon_identity_info_get_id
+signon_identity_info_get_identity_type
+signon_identity_info_get_methods
+signon_identity_info_get_realms
+signon_identity_info_get_storing_secret
+signon_identity_info_get_username
+signon_identity_info_new
+signon_identity_info_remove_method
+signon_identity_info_set_access_control_list
+signon_identity_info_set_caption
+signon_identity_info_set_identity_type
+signon_identity_info_set_method
+signon_identity_info_set_realms
+signon_identity_info_set_secret
+signon_identity_info_set_username
+<SUBSECTION Standard>
+SIGNON_TYPE_IDENTITY_TYPE
+signon_identity_info_get_type
+signon_identity_type_get_type
+</SECTION>