docs: Added initial documentation

10 files changed, 220 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index 7f82a6e..adf3f41 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -1,6 +1,6 @@
 include $(top_srcdir)/Makefile.decl
 
-SUBDIRS = libmediaart
+SUBDIRS = libmediaart docs
 
 if HAVE_UNIT_TESTS
 SUBDIRS += tests
diff --git a/autogen.sh b/autogen.sh
index dbd91ce..b358491 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -5,7 +5,10 @@
 test -n "$srcdir" || srcdir=`dirname "$0"`
 test -n "$srcdir" || srcdir=.
 (
-  touch ChangeLog # Required by automake.
+  cd "$srcdir" &&
+  touch ChangeLog && # Required by automake.
+  (test -d m4 || mkdir m4) && # Required by gtkdocize
+  gtkdocize &&
   autoreconf --verbose --force --install
 ) || exit
 
diff --git a/configure.ac b/configure.ac
index d9627ba..8d82ccf 100644
--- a/configure.ac
+++ b/configure.ac
@@ -157,6 +157,23 @@ AC_SUBST(BUILD_VALAFLAGS)
 AC_SUBST(BUILD_CFLAGS)
 AC_SUBST(BUILD_LIBS)
 
+####################################################################
+# Check for gtk-doc and docbook-tools
+####################################################################
+
+# Check for GTK_DOC_CHECK availability. The GTK_DOC_CHECK invocation
+# must be on its own line, gtkdocize relies on it
+m4_ifdef([GTK_DOC_CHECK], [
+GTK_DOC_CHECK([1.8])
+
+# NOTE: We need to use a separate automake conditional for this
+#       to make this work with the tarballs.
+AM_CONDITIONAL([ENABLE_GTK_DOC], test "x$enable_gtk_doc" = xyes)
+],
+[
+AM_CONDITIONAL([ENABLE_GTK_DOC], false)
+])
+
 ##################################################################
 # Check for tracker-extract: GdkPixbuf for MP3 album art
 ##################################################################
@@ -263,6 +280,10 @@ AC_CONFIG_FILES([
 	Makefile
 	libmediaart/Makefile
 	tests/Makefile
+	docs/Makefile
+	docs/reference/Makefile
+	docs/reference/libmediaart/Makefile
+	docs/reference/libmediaart/version.xml
 ])
 
 AC_OUTPUT
@@ -276,6 +297,7 @@ Build Configuration:
 	Compiler Warnings:                      $enable_compile_warnings
 
 	Enable unit tests:                      $have_unit_tests
+	Enable documentation:                   $enable_gtk_doc
 
 	Support media art processing:           $selected_for_media_art
 "
diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..34905f5
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,15 @@
+include $(top_srcdir)/Makefile.decl
+
+SUBDIRS = reference
+
+# require gtk-doc when making dist
+#
+if ENABLE_GTK_DOC
+dist-check-gtk-doc:
+else
+dist-check-gtk-doc:
+	@echo "*** gtk-doc must be enabled in order to make dist"
+	@false
+endif
+
+dist-hook: dist-check-gtk-doc
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..a68f8d3
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,3 @@
+include $(top_srcdir)/Makefile.decl
+
+SUBDIRS = libmediaart
diff --git a/docs/reference/libmediaart/Makefile.am b/docs/reference/libmediaart/Makefile.am
new file mode 100644
index 0000000..60ab37f
--- /dev/null
+++ b/docs/reference/libmediaart/Makefile.am
@@ -0,0 +1,57 @@
+include $(top_srcdir)/Makefile.decl
+
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module.
+DOC_MODULE=libmediaart
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=libmediaart-docs.sgml
+
+# Extra options to supply to gtkdoc-scan
+SCAN_OPTIONS=
+
+# Extra options to pass to gtkdoc-scangobj
+# SCANGOBJ_OPTIONS=--type-init-func="gtk_type_init(0)"
+
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR=../../../libmediaart
+
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/libmediaart/*.h
+CFILE_GLOB=$(top_srcdir)/libmediaart/*.c
+
+# Header files to ignore when scanning
+IGNORE_HFILES=
+
+# CFLAGS and LDFLAGS for compiling scan program. Only needed
+# if $(DOC_MODULE).types is non-empty.
+AM_CPPFLAGS = \
+	-DMEDIAART_COMPILATION \
+	$(LIBMEDIAART_CFLAGS)
+
+GTKDOC_LIBS = \
+	$(top_builddir)/src/libmediaart/libmediaart-@MEDIAART_API_VERSION@.la \
+	$(LIBMEDIAART_LIBS)
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=--path="$(abs_builddir)"
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE)
+content_files = version.xml overview.sgml
+
+expand_content_files =
+
+# Images to copy into HTML directory
+HTML_IMAGES =
+
+# Extra options to supply to gtkdoc-fixref
+FIXXREF_OPTIONS=
+
+include $(top_srcdir)/gtk-doc.make
+
+# Other files to distribute
+EXTRA_DIST += version.xml.in
diff --git a/docs/reference/libmediaart/libmediaart-docs.sgml b/docs/reference/libmediaart/libmediaart-docs.sgml
new file mode 100644
index 0000000..3fbf6f2
--- /dev/null
+++ b/docs/reference/libmediaart/libmediaart-docs.sgml
@@ -0,0 +1,41 @@
+<?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" [
+<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+  <bookinfo>
+    <title>libmediaart Library Reference Manual</title>
+    <releaseinfo>
+	  for libmediaart &version;.
+	  The latest version of this documentation can be found on-line at
+	  <ulink role="online-location" url="http://library.gnome.org/devel/libmediaart/unstable/">
+		http://library.gnome.org/devel/libmediaart/unstable
+	  </ulink>.
+	</releaseinfo>
+  </bookinfo>
+
+  <!-- The Library Overview -->
+  <xi:include href="overview.sgml"/>
+
+  <!-- The API Reference -->
+  <part id="libmediaart-reference">
+    <title>Reference</title>
+    <partintro>
+      <para>
+        This section provides the detailed API of the libmediaart library.
+      </para>
+    </partintro>
+
+    <chapter>
+      <title>Reference</title>
+      <xi:include href="xml/extract.xml" title="Extraction"/>
+      <xi:include href="xml/cache.xml" title="Lookup and caching"/>
+      <xi:include href="xml/utils.xml" title="Utilities"/>
+    </chapter>
+
+  </part>
+
+  <xi:include href="xml/annotation-glossary.xml"><xi:fallback /></xi:include>
+</book>
diff --git a/docs/reference/libmediaart/libmediaart-sections.txt b/docs/reference/libmediaart/libmediaart-sections.txt
new file mode 100644
index 0000000..17a26e4
--- /dev/null
+++ b/docs/reference/libmediaart/libmediaart-sections.txt
@@ -0,0 +1,32 @@
+<SECTION>
+<FILE>cache</FILE>
+media_art_remove
+</SECTION>
+
+<SECTION>
+<FILE>extract</FILE>
+MediaArtType
+media_art_init
+media_art_process
+media_art_shutdown
+</SECTION>
+
+<SECTION>
+<FILE>extractgeneric</FILE>
+media_art_buffer_to_jpeg
+media_art_file_to_jpeg
+media_art_plugin_init
+media_art_plugin_shutdown
+</SECTION>
+
+<SECTION>
+<FILE>mediaart</FILE>
+
+</SECTION>
+
+<SECTION>
+<FILE>utils</FILE>
+media_art_get_path
+media_art_strip_invalid_entities
+</SECTION>
+
diff --git a/docs/reference/libmediaart/overview.sgml b/docs/reference/libmediaart/overview.sgml
new file mode 100644
index 0000000..a5623e4
--- /dev/null
+++ b/docs/reference/libmediaart/overview.sgml
@@ -0,0 +1,44 @@
+<?xml version='1.0' encoding="ISO-8859-1"?>
+
+<part id="tracker-overview">
+  <title>Overview</title>
+  <partintro>
+    <para>
+      The libmediaart library is the foundation for media art caching,
+      extraction and lookup for applications on the desktop.
+    </para>
+  </partintro>
+
+  <chapter id="tracker-overview-compiling">
+    <title>Compiling applications</title>
+
+    <para>
+      To compile applications using libtracker-miner, you
+      need to tell the compiler where to find the proper header files
+      and libraries. This is done with the
+      <application>pkg-config</application> utility.
+    </para>
+
+    <para>
+      The following interactive shell session demonstrates how
+      <application>pkg-config</application> is used (the actual output on
+      your system may be different):
+<programlisting>
+$ pkg-config --cflags libmediaart-0.2
+
+$ pkg-config --libs libmediaart-0.2
+
+</programlisting>
+    </para>
+    <para>
+      The simplest way to compile a program is to use the "backticks"
+      feature of the shell. If you enclose a command in backticks
+      (<emphasis>not single quotes</emphasis>), then its output will be
+      substituted into the command line before execution:
+<programlisting>
+ $ cc `pkg-config --cflags --libs libmediaart-0.2` hello.c -o hello
+</programlisting>
+    </para>
+
+  </chapter>
+</part>
diff --git a/docs/reference/libmediaart/version.xml.in b/docs/reference/libmediaart/version.xml.in
new file mode 100644
index 0000000..34b3385
--- /dev/null
+++ b/docs/reference/libmediaart/version.xml.in
@@ -0,0 +1 @@
+@LIBMEDIAART_VERSION@