[docs] Modernise API docs

Use no-tmpl gtk-doc option.
Use xi:include, add index and object hierarchy, etc.

autogen.sh

@@ -17,4 +17,7 @@ which gnome-autogen.sh || {
     exit 1
 }
 
-REQUIRED_AUTOMAKE_VERSION=1.9 USE_GNOME2_MACROS=1 . gnome-autogen.sh
+REQUIRED_AUTOMAKE_VERSION=1.10
+REQUIRED_GTK_DOC_VERSION=1.13
+USE_GNOME2_MACROS=1
+. gnome-autogen.sh

configure.ac

@@ -41,7 +41,7 @@ m4_define([ev_binary_version],[ev_document_lt_current])
 
 AC_PREREQ([2.57])
 AC_INIT([Evince],[ev_version],[http://bugzilla.gnome.org/enter_bug.cgi?product=evince],[evince])
-AM_INIT_AUTOMAKE([1.9 foreign dist-bzip2 no-dist-gzip])
+AM_INIT_AUTOMAKE([1.10 foreign dist-bzip2 no-dist-gzip])
 
 AC_CONFIG_HEADERS([config.h])
 AC_CONFIG_MACRO_DIR([m4])
@@ -66,14 +66,11 @@ AC_PROG_SED
 AC_PATH_PROG([GLIB_GENMARSHAL], [glib-genmarshal])
 AC_PATH_PROG([GLIB_MKENUMS],[glib-mkenums])
 
-GNOME_COMMON_INIT
 GNOME_DOC_INIT
 GNOME_MAINTAINER_MODE_DEFINES
 GNOME_COMPILE_WARNINGS
 GNOME_CXX_WARNINGS
 
-GTK_DOC_CHECK(1.0)
-
 IT_PROG_INTLTOOL([0.35.0])
 
 GETTEXT_PACKAGE=evince
@@ -261,9 +258,6 @@ if test "$with_keyring" = "yes"; then
         AC_DEFINE([WITH_KEYRING],[1],[Define if KEYRING support is enabled])
 fi
 
-GLIB_GENMARSHAL=`$PKG_CONFIG --variable=glib_genmarshal glib-2.0`  
-AC_SUBST(GLIB_GENMARSHAL)
-
 # ****
 # DBUS
 # ****
@@ -713,12 +707,25 @@ AC_SUBST(EVINCE_MIME_TYPES)
 
 AC_CHECK_FUNC(localtime_r, AC_DEFINE(HAVE_LOCALTIME_R, 1, [Defines if localtime_r is available on your system]))
 
+# *****************
+# API documentation
+# *****************
+
+GTK_DOC_CHECK([1.13],[--flavour no-tmpl])
+
+AC_SUBST([GLIB_PREFIX],[$($PKG_CONFIG --variable=prefix glib-2.0)])
+AC_SUBST([GTK_PREFIX],[$($PKG_CONFIG --variable=prefix gtk+-2.0)])
+
+# ******************
 # Backends directory
+# ******************
 
 AC_SUBST([backenddir],"\$(libdir)/evince/ev_binary_version/backends")
 AC_SUBST([backend_binary_version],"ev_binary_version")
 
+# **********
 # Versioning
+# **********
 
 AC_SUBST([EV_MAJOR_VERSION],[ev_major_version])
 AC_SUBST([EV_MINOR_VERSION],[ev_minor_version])
@@ -732,6 +739,7 @@ AC_SUBST([EV_DOCUMENT_LT_CURRENT_MINUS_AGE],[ev_document_lt_current_minus_age])
 AC_SUBST([EV_VIEW_LT_VERSION_INFO],[ev_view_lt_version_info])
 AC_SUBST([EV_VIEW_LT_CURRENT_MINUS_AGE],[ev_view_lt_current_minus_age])
 
+# *****************************************************************************
 # *****************************************************************************
 
 AC_CONFIG_FILES([

help/reference/libdocument/Makefile.am

@@ -1,79 +1,97 @@
-## Process this file with automake to produce Makefile.in
-
-# We require automake 1.6 at least.
-AUTOMAKE_OPTIONS = 1.6
+# We require automake 1.10 for $(abs_builddir)
+AUTOMAKE_OPTIONS = 1.10
 
 # This is a blank Makefile.am for using gtk-doc.
 # Copy this to your project's API docs directory and modify the variables to
 # suit your project. See the GTK+ Makefiles in gtk+/docs/reference for examples
 # of using the various options.
 
 # The name of the module, e.g. 'glib'.
-DOC_MODULE=libevdocument
+DOC_MODULE = libevdocument
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+DOC_MODULE_VERSION = $(EV_API_VERSION)
+
 
 # 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=../../../libdocument
+DOC_SOURCE_DIR = ../../../libdocument
 
 # Extra options to pass to gtkdoc-scangobj. Not normally needed.
-SCANGOBJ_OPTIONS=
+SCANGOBJ_OPTIONS =
 
 # Extra options to supply to gtkdoc-scan.
-# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" 
-SCAN_OPTIONS=
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS =
 
 # 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 = --sgml-mode --output-format=xml --name-space=ev
 
 # Extra options to supply to gtkdoc-mktmpl
 # e.g. MKTMPL_OPTIONS=--only-section-tmpl
-MKTMPL_OPTIONS=
+MKTMPL_OPTIONS =
 
+# Extra options to supply to gtkdoc-mkhtml
 # Add the builddir to the HTML path so that version.xml is found
-MKHTML_OPTIONS=--path="$(abs_builddir)"
+MKHTML_OPTIONS = --path="$(abs_builddir)"
 
 # Extra options to supply to gtkdoc-fixref. Not normally needed.
 # e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
-FIXXREF_OPTIONS=
+FIXXREF_OPTIONS = \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/glib \
+	--extra-dir=$(GLIB_PREFIX)/share/gtk-doc/html/gio \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gdk-pixbuf \
+	--extra-dir=$(GTK_PREFIX)/share/gtk-doc/html/gtk
 
 # Used for dependencies. The docs will be rebuilt if any of these change.
 # e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
 # e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
-HFILE_GLOB=$(top_srcdir)/libdocument/*.h
-CFILE_GLOB=$(top_srcdir)/libdocument/*.c
+HFILE_GLOB = \
+	$(top_srcdir)/libdocument/*.h \
+	$(top_builddir)/libdocument/*.h
+
+CFILE_GLOB = \
+	$(top_srcdir)/libdocument/*.c
+
+# Extra header to include when scanning, which are not under DOC_SOURCE_DIR
+# e.g. EXTRA_HFILES=$(top_srcdir}/contrib/extra.h
+# EXTRA_HFILES = $(top_builddir)/evdocument/ev-version.h
+EXTRA_HFILES =
 
-# Header files to ignore when scanning.
+# Header files to ignore when scanning. Use base file name, no paths
 # e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
-IGNORE_HFILES=  \
-	ev-debug.h	\
+IGNORE_HFILES = \
+	config.h \
+	ev-debug.h \
 	ev-module.h
 
 # Images to copy into HTML directory.
 # e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
-HTML_IMAGES=
+HTML_IMAGES =
 
 # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
-content_files= \
-	version.xml
+content_files = \
+ 	version.xml
 
 # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
 # These files must be listed here *and* in content_files
 # e.g. expand_content_files=running.sgml
-expand_content_files=
+expand_content_files =
 
 # CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
 # Only needed if you are using gtkdoc-scangobj to dynamically query widget
 # signals and properties.
-# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
 # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
-INCLUDES= \
+GTKDOC_CFLAGS = \
 	-I$(top_srcdir)					\
 	-I$(top_builddir)				\
 	-I$(top_srcdir)/libdocument 			\
@@ -88,7 +106,7 @@ INCLUDES= \
 	$(WARN_CFLAGS)					\
 	$(DISABLE_DEPRECATED)
 
-GTKDOC_LIBS=						\
+GTKDOC_LIBS = \
 	$(top_builddir)/libdocument/libevdocument.la	\
 	$(LIBDOCUMENT_LIBS)
 
@@ -97,6 +115,18 @@ include $(top_srcdir)/gtk-doc.make
 
 # Other files to distribute
 # e.g. EXTRA_DIST += version.xml.in
-EXTRA_DIST += version.xml.in
+EXTRA_DIST += \
+	version.xml.in
+
+# Files not to distribute
+# for --rebuild-types in $(SCAN_OPTIONS), e.g. $(DOC_MODULE).types
+# for --rebuild-sections in $(SCAN_OPTIONS) e.g. $(DOC_MODULE)-sections.txt
+#DISTCLEANFILES +=
+
+# Comment this out if you want your docs-status tested during 'make check'
+if ENABLE_GTK_DOC
+#TESTS_ENVIRONMENT = cd $(srcsrc) &&
+#TESTS = $(GTKDOC_CHECK)
+endif
 
 -include $(top_srcdir)/git.mk