Move documentation generating to Valadoc

Generating Vala documentation with GTK-Doc is a bit of PITA. Using Valadoc is much easier, so we are moving there.
2016-03-04 14:43:31 +01:00 · 2016-03-04 14:43:31 +01:00 · e93a7675c0
commit e93a7675c0
parent 6356ead2b2
9 changed files with 104 additions and 68 deletions
--- a/.gitignore
+++ b/.gitignore
@ -39,22 +39,7 @@ Makefile.in
 /src/matrix-version.h
 /src/matrix-marshalers.[ch]
 /src/stamp-matrix-marshalers
-/docs/reference/matrix-glib/version.xml
-/docs/reference/matrix-glib/html/
-/docs/reference/matrix-glib/xml/
-/docs/reference/matrix-glib/matrix-glib-decl-list.txt
-/docs/reference/matrix-glib/matrix-glib-decl.txt
-/docs/reference/matrix-glib/matrix-glib-overrides.txt
-/docs/reference/matrix-glib/matrix-glib-undeclared.txt
-/docs/reference/matrix-glib/matrix-glib-undocumented.txt
-/docs/reference/matrix-glib/matrix-glib-unused.txt
-/docs/reference/matrix-glib/matrix-glib.args
-/docs/reference/matrix-glib/matrix-glib.hierarchy
-/docs/reference/matrix-glib/matrix-glib.interfaces
-/docs/reference/matrix-glib/matrix-glib.prerequisites
-/docs/reference/matrix-glib/matrix-glib.signals
-/docs/reference/matrix-glib/matrix-glib.types
-/docs/reference/matrix-glib/*.bak
+/docs/valadoc/gtk-doc/gtk-doc

 # Vala related files
 /src/Matrix-0.0.vapi
--- a/Makefile.am
+++ b/Makefile.am
@ -3,8 +3,8 @@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
 # Set up subdirectories to traverse
 SUBDIRS = src

-if ENABLE_GTK_DOC
-SUBDIRS += docs/reference/matrix-glib
+if ENABLE_DOCS
+    SUBDIRS += docs
 endif

 # Specify files to include in dist
--- a/autogen.sh
+++ b/autogen.sh
@ -93,21 +93,6 @@ if grep "^LT_INIT" "$coin" > /dev/null; then
    fi
 fi

-GTKDOCIZE=$(which gtkdocize 2> /dev/null)
-
-if test -z "$GTKDOCIZE"; then
-    echo "You don't have gtk-doc installed, and thus won't be able to generate documentation"
-    rm -f gtk-doc.make
-    rm -f $m4_dir/gtk-doc.m4
-    cat > gtk-doc.make <<EOF
-EXTRA_DIST =
-CLEANFILES =
-EOF
-else
-    echo "Running gtkdocize ..."
-    gtkdocize --copy || exit $?
-fi
-
 echo "Running aclocal $aclocalinclude ..."
 aclocal $m4dir $ACLOCAL_FLAGS $aclocalinclude || exit $?

--- a/configure.ac
+++ b/configure.ac
@ -94,6 +94,7 @@ GEE_REQUIRED=0.10.5
 GIO_REQUIRED=2.22
 SOUP_REQUIRED=2.44.2
 JSON_REQUIRED=0.16.2
+VALADOC_REQUIRED=0.3.1

 # Check GLib
 PKG_CHECK_MODULES([GLIB],
@ -118,6 +119,52 @@ PKG_CHECK_MODULES([JSON], [json-glib-1.0 >= $JSON_REQUIRED])
 # Check for GObject Introspection
 GOBJECT_INTROSPECTION_CHECK([1.32.0])

+# Documentation with Valadoc
+AC_ARG_ENABLE([docs],
+              AS_HELP_STRING([--enable-docs],
+                             [Enable documentation generation]),
+              [enable_docs=$enableval], [enable_docs=no])
+AM_CONDITIONAL([ENABLE_DOCS], [test x$enable_docs = xyes])
+
+have_valadoc=no
+if test x$enable_docs = xyes; then
+    # Make sure the library is new enough and the program exists
+    AC_PATH_PROG([VALADOC], [valadoc], [no])
+    if test "x$VALADOC" = "xno"; then
+        AC_MSG_RESULT([valadoc documentation will not build because valadoc is not found])
+    else
+        VAPIDIR=`$PKG_CONFIG --variable=vapidir libvala-$LIBVALA_REQUIRED`
+        have_valadoc="yes"
+        AC_SUBST([VALADOC])
+    fi
+fi
+AM_CONDITIONAL([HAVE_VALADOC], [test x$have_valadoc = xyes])
+
+AC_ARG_ENABLE([gtk-doc],
+              AS_HELP_STRING([--enable-gtk-doc],
+                             [Enable GTK-Doc documentation generation]),
+              [enable_gtk_docs=$enableval], [enable_gtk_docs=no])
+
+have_gtkdoc=no
+if test x$enable_gtk_docs = xyes; then
+    if test x$have_valadoc = xyes; then
+        PKG_CHECK_MODULES([GTKDOC], gtk-doc)
+        have_gtkdoc=yes
+    else
+        AC_MSG_ERROR([valadoc is required to generate GTK-Doc documentation. Use --enable-valadoc])
+    fi
+fi
+
+gtkdocs=no
+
+if test x$enable_docs = xyes; then
+    if test x$enable_gtk_docs = xyes; then
+        gtkdocs=yes
+    fi
+fi
+
+AM_CONDITIONAL([ENABLE_GTK_DOCS], [test "x$gtkdocs" = "xyes"])
+
 debug=no
 AC_ARG_ENABLE(debug,
              AS_HELP_STRING([--enable-debug],
@ -148,25 +195,15 @@ AC_SUBST([MATRIX_GLIB_MICRO_VERSION], matrix_glib_micro_version)
 #   a new API, too
 AC_SUBST([MATRIX_GLIB_API_VERSION], matrix_glib_api_version)

-m4_ifdef([GTK_DOC_CHECK], [
-GTK_DOC_CHECK([1.20], [--flavour no-tmpl])
-], [
-AM_CONDITIONAL([ENABLE_GTK_DOC], false)
-])
-
-AC_PATH_PROG([GLIB_MKENUMS], [glib-mkenums])
 AC_PATH_PROG([GLIB_GENMARSHAL], [glib-genmarshal])

 AC_CONFIG_FILES([
    Makefile
    src/Makefile
    src/matrix-version.h
-])
-AM_COND_IF([ENABLE_GTK_DOC], [
-  AC_CONFIG_FILES([
-    docs/reference/matrix-glib/version.xml
-    docs/reference/matrix-glib/Makefile
-  ])
+    docs/Makefile
+    docs/valadoc/Makefile
+    docs/valadoc/gtk-doc/Makefile
 ])
 AC_OUTPUT

@ -174,5 +211,7 @@ AC_OUTPUT
 echo ""
 echo " Configuration summary for Matrix-$MATRIX_GLIB_VERSION"
 echo "   Installation prefix:     $prefix"
+echo "   Documentation:           ${enable_docs}"
+echo "       Gtk-Doc:             `if test x${gtkdocs} = xyes; then echo yes; else echo no; fi`"
 echo "   Debug:                   $debug"
 echo ""
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@ -0,0 +1,5 @@
+SUBDIRS =
+
+if HAVE_VALADOC
+    SUBDIRS += valadoc
+endif
--- a/docs/valadoc/Makefile.am
+++ b/docs/valadoc/Makefile.am
@ -0,0 +1,5 @@
+SUBDIRS =
+
+if ENABLE_GTK_DOCS
+    SUBDIRS += gtk-doc
+endif
--- a/docs/valadoc/gtk-doc/Makefile.am
+++ b/docs/valadoc/gtk-doc/Makefile.am
@ -0,0 +1,28 @@
+include $(top_srcdir)/vala-globals.mk
+CLEANFILES =
+
+sources = $(top_srcdir)/src/*.vala
+
+gtkdocdir = $(datadir)/gtk-doc/html/matrix-glib
+gtkdoc_DATA = \
+	gtk-doc/matrix-glib/*.txt \
+	gtk-doc/matrix-glib/*.xml \
+	gtk-doc/matrix-glib/xml/*.xml \
+	gtk-doc/matrix-glib/xml/*.top \
+	gtk-doc/matrix-glib/xml/*.bottom \
+	gtk-doc/matrix-glib/*.types \
+	gtk-doc/matrix-glib/sgml.stamp \
+	$(NULL)
+
+$(gtkdoc_DATA): matrix-glib-gtk-doc
+
+matrix-glib-gtk-doc:
+	$(VALADOC) -o gtk-doc/matrix-glib --doclet=gtkdoc \
+	    -X $(top_builddir)/src/matrix-glib.h \
+	    $(VALADOC_FLAGS) $(sources)
+
+all: matrix-glib-gtk-doc
+
+clean-local:
+	rm -rf gtk-doc
+	rm -rf matrix-glib
--- a/src/matrix-version.c
+++ b/src/matrix-version.c
@ -18,28 +18,6 @@

 #include "matrix-version.h"

-/**
- * SECTION:matrix-version
- * @short_description: Matrix.org GLib SDK version information
- * @title: Version information
- * @stability: Stable
- * @include: matrix-client/matrix-client.h
- *
- * Version information for the Matrix.org GLib SDK.
- */
-
-/**
- * MATRIX_GLIB_CHECK_VERSION:
- * @major: the major version to check for
- * @minor: the minor version to check for
- * @micro: the micro version to check for
- *
- * Checks the version number of the Matrix.org GLib SDK that is being
- * compiled against.
- *
- * Returns: TRUE if the required version is satisfied; FALSE otherwise.
- */
-
 gboolean
 matrix_glib_check_version(guint required_major,
                          guint required_minor,
--- a/vala-globals.mk
+++ b/vala-globals.mk
@ -4,3 +4,14 @@ VALA_PKG_LIST = \
 	--pkg=libsoup-2.4 \
 	--pkg=gee-0.8 \
 	$(NULL)
+
+VALADOC_FLAGS = \
+	--driver $(VALAC_VERSION) \
+	--force \
+	--package-name=Matrix-$(MATRIX_GLIB_API_VERSION) \
+	--package-version=$(PACKAGE_VERSION) \
+	-b $(top_srcdir)/src \
+	$(VALA_PKG_LIST) \
+	--vapidir=$(top_srcdir)/src \
+	$(top_srcdir)/src/c-api.vapi \
+	$(NULL)