From c2b598fe28074850b03ae57d15c8a9f630b0c548 Mon Sep 17 00:00:00 2001
From: Murray Cumming <murrayc@murrayc.com>
Date: Tue, 26 Jun 2012 14:44:19 +0200
Subject: [PATCH] doc: Generate API documentation with valadoc

* configure.ac: Check for valadoc, optionally.
* src/librygel-core/Makefile.am: Move some lists of files and
  options into filelist.am so it can be used here too:
* doc/reference/librygel-core/Makefile.am: Use valadoc to generate
  API reference documentation.
---
 Makefile.am                             |  3 +-
 common.am                               |  6 +-
 configure.ac                            | 21 +++++++
 doc/Makefile.am                         |  2 +
 doc/reference/Makefile.am               |  1 +
 doc/reference/librygel-core/Makefile.am | 67 ++++++++++++++++++++++
 src/librygel-core/Makefile.am           | 99 ++-------------------------------
 src/librygel-core/filelist.am           | 97 ++++++++++++++++++++++++++++++++
 8 files changed, 198 insertions(+), 98 deletions(-)
 create mode 100644 doc/reference/Makefile.am
 create mode 100644 doc/reference/librygel-core/Makefile.am
 create mode 100644 src/librygel-core/filelist.am

diff --git a/Makefile.am b/Makefile.am
index 76e701a..4da1019 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -6,7 +6,8 @@ pkgconfigdir = $(libdir)/pkgconfig
 EXTRA_DIST = rygel-core-1.0.pc.in rygel-renderer-1.0.pc.in \
              .version
 
-DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc
+DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc \
+                            --enable-valadoc
 
 # Extra clean files so that maintainer-clean removes *everything*
 MAINTAINERCLEANFILES = aclocal.m4 compile config.guess config.sub configure depcomp install-sh ltmain.sh Makefile.in missing config.h.in
diff --git a/common.am b/common.am
index dbaf065..d40fc33 100644
--- a/common.am
+++ b/common.am
@@ -55,11 +55,13 @@ RYGEL_COMMON_PLUGIN_VALAFLAGS = \
 	--pkg rygel-core-1.0 \
 	$(RYGEL_COMMON_VALAFLAGS)
 
+RYGEL_COMMON_VALAFLAGS_PKG = --pkg gupnp-1.0 --pkg gupnp-av-1.0 --pkg gee-1.0
+
 RYGEL_COMMON_VALAFLAGS = \
-	--pkg rygel-build-config --pkg gupnp-1.0 \
+	--pkg rygel-build-config \
 	--vapidir=$(rygeldir) \
 	--vapidir=$(librygelcoredir) \
-	--pkg gupnp-av-1.0 --pkg gee-1.0 \
+	$(RYGEL_COMMON_VALAFLAGS_PKG)
 	$(RYGEL_DEBUG_VALAFLAGS) \
 	$(COVERAGE_VALAFLAGS)
 
diff --git a/configure.ac b/configure.ac
index e229a11..8e9ec73 100644
--- a/configure.ac
+++ b/configure.ac
@@ -30,6 +30,7 @@ LT_INIT([dlopen disable-static])
 dnl Required versions of library packages
 GLIB_REQUIRED=2.31.13
 VALA_REQUIRED=0.15.2
+VALADOC_REQUIRED=0.2
 GSSDP_REQUIRED=0.11.0
 GUPNP_REQUIRED=0.17.1
 GUPNP_AV_REQUIRED=0.9.0
@@ -202,6 +203,24 @@ dnl documenation
 AC_PATH_PROG([XSLTPROC], [xsltproc])
 AM_CONDITIONAL([HAVE_XSLTPROC], [test x"$XSLTPROC" != x])
 
+dnl Use valadoc for API documentation:
+AC_ARG_ENABLE(valadoc,
+  AS_HELP_STRING([--enable-valadoc[=@<:@no/auto/yes@:>@]], [Enable valadoc support]),,
+    [enable_valadoc=auto])
+
+found_valadoc=no
+AS_IF([test "x$enable_valadoc" != "xno"], [
+    AC_PATH_PROG(VALADOC, valadoc, :)
+    AS_IF([test -x "$VALADOC"], [
+      found_valadoc=yes
+      AC_SUBST(VALADOC)
+    ], [
+      AS_IF([test "x$enable_valadoc" == "xyes"], AC_MSG_ERROR([Unable to find valadoc]))
+    ])
+  ])
+
+AM_CONDITIONAL(ENABLE_VALADOC, test x$found_valadoc = xyes)
+
 
 AC_CONFIG_FILES([
 Makefile
@@ -222,6 +241,8 @@ data/icons/scalable/Makefile
 data/rygel.desktop.in
 data/rygel-preferences.desktop.in
 doc/Makefile
+doc/reference/Makefile
+doc/reference/librygel-core/Makefile
 po/Makefile.in
 rygel-core-1.0.pc
 rygel-renderer-1.0.pc
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 0960fb9..8f76a21 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,5 @@
+SUBDIRS = reference
+
 dist_man1_MANS = \
 		rygel.1
 
diff --git a/doc/reference/Makefile.am b/doc/reference/Makefile.am
new file mode 100644
index 0000000..158267a
--- /dev/null
+++ b/doc/reference/Makefile.am
@@ -0,0 +1 @@
+SUBDIRS = librygel-core
diff --git a/doc/reference/librygel-core/Makefile.am b/doc/reference/librygel-core/Makefile.am
new file mode 100644
index 0000000..0c946e7
--- /dev/null
+++ b/doc/reference/librygel-core/Makefile.am
@@ -0,0 +1,67 @@
+if ENABLE_VALADOC
+
+include $(top_srcdir)/common.am
+include $(top_srcdir)/src/librygel-core/filelist.am
+
+# TODO: Generate API documentation for LIBRYGEL_CORE_VAPI_SOURCE_FILES,
+# without generating it for the LIBRYGEL_CORE_NONVAPI_SOURCE_FILES files
+# that are also needed by valadoc.
+VALA_SOURCE_FILES = $(LIBRYGEL_CORE_VAPI_SOURCE_FILES) \
+		$(LIBRYGEL_CORE_NONVAPI_SOURCE_FILES)
+
+VALA_SOURCE_FILES_WITH_PATHS = $(addprefix $(top_srcdir)/src/librygel-core/, $(VALA_SOURCE_FILES))
+
+# TODO: The need for rygel-build-config here reminds us that we shouldn't need that in librygel-core either.
+# TODO: Why is gstreamer-pbutils-0.10 needed here, but not needed in librygel-core/Makefile.am?
+VALADOC_FLAGS = --force \
+		--vapidir $(top_srcdir)/src/librygel-core \
+		$(RYGEL_COMMON_VALAFLAGS_PKG) \
+		$(LIBRYGEL_CORE_VALAFLAGS_PKG) \
+	        --pkg gstreamer-pbutils-0.10 \
+	        --target-glib=2.32 \
+	        --vapidir=$(rygeldir) \
+	        --pkg rygel-build-config \
+		-b $(top_srcdir)/src/librygel-core \
+		--package-name librygel-core \
+		--package-version 1.0 \
+		$(VALA_SOURCE_FILES_WITH_PATHS)
+
+valadoc:
+	$(VALADOC) \
+		-o valadoc \
+		$(VALADOC_FLAGS) \
+		$(NULL)
+
+devhelp:
+	$(VALADOC) \
+		-o devhelp \
+		--doclet devhelp \
+		$(VALADOC_FLAGS) \
+		$(NULL)
+
+gtkdoc:
+	$(VALADOC) \
+		-X $(top_builddir)/src/librygel-core/rygel-core.h \
+		-X -l -X $(top_builddir)/src/librygel-core/.libs/librygel-core-1.0.so \
+		-o gtkdoc \
+		--doclet gtkdoc \
+		$(VALADOC_FLAGS) \
+		$(NULL)
+
+clean-local:
+	rm -rf valadoc devhelp gtkdoc
+
+uninstall-hook:
+	rm -rf $(DESTDIR)$(datadir)/devhelp/books/librygel-core
+	rm -rf $(DESTDIR)$(datadir)/gtk-doc/html/librygel-core
+
+install-data-hook: devhelp gtkdoc
+	$(MKDIR_P) $(DESTDIR)$(datadir)/devhelp/books/librygel-core/img
+	$(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/librygel-core devhelp/librygel-core/*.*
+	$(INSTALL_DATA) -t $(DESTDIR)$(datadir)/devhelp/books/librygel-core/img devhelp/librygel-core/img/*
+	$(MKDIR_P) $(DESTDIR)$(datadir)/gtk-doc/html/librygel-core
+	cp -R gtkdoc/html $(DESTDIR)$(datadir)/gtk-doc/html/librygel-core
+
+all: valadoc devhelp gtkdoc
+
+endif
diff --git a/src/librygel-core/Makefile.am b/src/librygel-core/Makefile.am
index 8060e7c..b2e0202 100644
--- a/src/librygel-core/Makefile.am
+++ b/src/librygel-core/Makefile.am
@@ -1,4 +1,5 @@
 include ../../common.am
+include $(srcdir)/filelist.am
 
 AM_CFLAGS += \
 	$(LIBGUPNP_DLNA_CFLAGS) \
@@ -15,105 +16,13 @@ librygelinc_HEADERS = rygel-core.h
 
 lib_LTLIBRARIES = librygel-core-1.0.la
 
-VAPI_SOURCE_FILES = \
-	rygel-cmdline-config.vala \
-	rygel-root-device.vala \
-	rygel-root-device-factory.vala \
-	rygel-audio-item.vala \
-	rygel-dbus-interface.vala \
-	rygel-icon-info.vala \
-	rygel-image-item.vala \
-	rygel-log-handler.vala \
-	rygel-logical-expression.vala \
-	rygel-media-art-store.vala \
-	rygel-media-objects.vala \
-	rygel-media-renderer-plugin.vala \
-	rygel-meta-config.vala \
-	rygel-music-item.vala \
-	rygel-photo-item.vala \
-	rygel-plugin-loader.vala \
-	rygel-plugin.vala \
-	rygel-relational-expression.vala \
-	rygel-resource-info.vala \
-	rygel-simple-container.vala \
-	rygel-subtitle.vala \
-	rygel-thumbnail.vala \
-	rygel-user-config.vala \
-	rygel-video-item.vala \
-	rygel-media-container.vala \
-	rygel-media-item.vala \
-	rygel-media-object.vala \
-	rygel-media-server-plugin.vala \
-	rygel-search-expression.vala \
-	rygel-configuration.vala \
-	rygel-free-desktop-interfaces.vala \
-	rygel-media-player.vala \
-	rygel-searchable-container.vala \
-	rygel-state-machine.vala \
-	rygel-visual-item.vala \
-	rygel-writable-container.vala \
-	rygel-xml-utils.vala
-
 librygel_core_1_0_la_SOURCES = \
-	$(VAPI_SOURCE_FILES) \
-	rygel-http-item-uri.vala \
-	rygel-environment-config.vala \
-	rygel-content-directory.vala \
-	rygel-connection-manager.vala \
-	rygel-source-connection-manager.vala \
-	rygel-sink-connection-manager.vala \
-	rygel-av-transport.vala \
-	rygel-rendering-control.vala \
-	rygel-transcode-manager.vala \
-	rygel-http-server.vala \
-	rygel-http-request.vala \
-	rygel-http-get-handler.vala \
-	rygel-http-get.vala \
-	rygel-http-post.vala \
-	rygel-http-identity-handler.vala \
-	rygel-http-transcode-handler.vala \
-	rygel-http-seek.vala \
-	rygel-http-byte-seek.vala \
-	rygel-http-time-seek.vala \
-	rygel-http-response.vala \
-	rygel-http-gst-sink.vala \
-	rygel-thumbnailer.vala \
-	rygel-dbus-thumbnailer.vala \
-	rygel-subtitle-manager.vala \
-	rygel-media-query-action.vala \
-	rygel-browse.vala \
-	rygel-search.vala \
-	rygel-client-hacks.vala \
-	rygel-xbox-hacks.vala \
-	rygel-panasonic-hacks.vala \
-	rygel-xbmc-hacks.vala \
-	rygel-wmp-hacks.vala \
-	rygel-v1-hacks.vala \
-	rygel-import-resource.vala \
-	rygel-item-creator.vala \
-	rygel-item-destroyer.vala \
-	rygel-item-removal-queue.vala \
-	rygel-search-criteria-parser.vala \
-	rygel-transcoder.vala \
-	rygel-audio-transcoder.vala \
-	rygel-video-transcoder.vala \
-	rygel-mp2ts-transcoder.vala \
-	rygel-mp3-transcoder.vala \
-	rygel-l16-transcoder.vala \
-	rygel-wmv-transcoder.vala \
-	rygel-aac-transcoder.vala \
-	rygel-avc-transcoder.vala \
-	rygel-gst-utils.vala \
-	rygel-media-receiver-registrar.vala \
-	rygel-changelog.vala \
-	rygel-volume.vala \
-	rygel-description-file.vala
+	$(LIBRYGEL_CORE_VAPI_SOURCE_FILES) \
+	$(LIBRYGEL_CORE_NONVAPI_SOURCE_FILES)
 
 librygel_core_1_0_la_VALAFLAGS = \
 	-H rygel-core.h -C --library=rygel-core-1.0 \
-	--pkg gstreamer-0.10 \
-	--pkg gstreamer-base-0.10 \
-	--pkg gupnp-dlna-1.0 \
+	$(LIBRYGEL_CORE_VALAFLAGS_PKG) \
 	$(RYGEL_COMMON_VALAFLAGS)
 
 librygel_core_1_0_la_LIBADD = \
diff --git a/src/librygel-core/filelist.am b/src/librygel-core/filelist.am
new file mode 100644
index 0000000..a61c4f3
--- /dev/null
+++ b/src/librygel-core/filelist.am
@@ -0,0 +1,97 @@
+LIBRYGEL_CORE_VAPI_SOURCE_FILES = \
+	rygel-cmdline-config.vala \
+	rygel-root-device.vala \
+	rygel-root-device-factory.vala \
+	rygel-audio-item.vala \
+	rygel-dbus-interface.vala \
+	rygel-icon-info.vala \
+	rygel-image-item.vala \
+	rygel-log-handler.vala \
+	rygel-logical-expression.vala \
+	rygel-media-art-store.vala \
+	rygel-media-objects.vala \
+	rygel-media-renderer-plugin.vala \
+	rygel-meta-config.vala \
+	rygel-music-item.vala \
+	rygel-photo-item.vala \
+	rygel-plugin-loader.vala \
+	rygel-plugin.vala \
+	rygel-relational-expression.vala \
+	rygel-resource-info.vala \
+	rygel-simple-container.vala \
+	rygel-subtitle.vala \
+	rygel-thumbnail.vala \
+	rygel-user-config.vala \
+	rygel-video-item.vala \
+	rygel-media-container.vala \
+	rygel-media-item.vala \
+	rygel-media-object.vala \
+	rygel-media-server-plugin.vala \
+	rygel-search-expression.vala \
+	rygel-configuration.vala \
+	rygel-free-desktop-interfaces.vala \
+	rygel-media-player.vala \
+	rygel-searchable-container.vala \
+	rygel-state-machine.vala \
+	rygel-visual-item.vala \
+	rygel-writable-container.vala \
+	rygel-xml-utils.vala
+
+LIBRYGEL_CORE_NONVAPI_SOURCE_FILES = \
+	rygel-http-item-uri.vala \
+	rygel-environment-config.vala \
+	rygel-content-directory.vala \
+	rygel-connection-manager.vala \
+	rygel-source-connection-manager.vala \
+	rygel-sink-connection-manager.vala \
+	rygel-av-transport.vala \
+	rygel-rendering-control.vala \
+	rygel-transcode-manager.vala \
+	rygel-http-server.vala \
+	rygel-http-request.vala \
+	rygel-http-get-handler.vala \
+	rygel-http-get.vala \
+	rygel-http-post.vala \
+	rygel-http-identity-handler.vala \
+	rygel-http-transcode-handler.vala \
+	rygel-http-seek.vala \
+	rygel-http-byte-seek.vala \
+	rygel-http-time-seek.vala \
+	rygel-http-response.vala \
+	rygel-http-gst-sink.vala \
+	rygel-thumbnailer.vala \
+	rygel-dbus-thumbnailer.vala \
+	rygel-subtitle-manager.vala \
+	rygel-media-query-action.vala \
+	rygel-browse.vala \
+	rygel-search.vala \
+	rygel-client-hacks.vala \
+	rygel-xbox-hacks.vala \
+	rygel-panasonic-hacks.vala \
+	rygel-xbmc-hacks.vala \
+	rygel-wmp-hacks.vala \
+	rygel-v1-hacks.vala \
+	rygel-import-resource.vala \
+	rygel-item-creator.vala \
+	rygel-item-destroyer.vala \
+	rygel-item-removal-queue.vala \
+	rygel-search-criteria-parser.vala \
+	rygel-transcoder.vala \
+	rygel-audio-transcoder.vala \
+	rygel-video-transcoder.vala \
+	rygel-mp2ts-transcoder.vala \
+	rygel-mp3-transcoder.vala \
+	rygel-l16-transcoder.vala \
+	rygel-wmv-transcoder.vala \
+	rygel-aac-transcoder.vala \
+	rygel-avc-transcoder.vala \
+	rygel-gst-utils.vala \
+	rygel-media-receiver-registrar.vala \
+	rygel-changelog.vala \
+	rygel-volume.vala \
+	rygel-description-file.vala
+
+LIBRYGEL_CORE_VALAFLAGS_PKG = \
+	--pkg gstreamer-0.10 \
+	--pkg gstreamer-base-0.10 \
+	--pkg gupnp-dlna-1.0
-- 
2.7.4