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.
This commit is contained in:
Gergely Polonkai 2016-03-04 14:43:31 +01:00
parent 6356ead2b2
commit e93a7675c0
9 changed files with 104 additions and 68 deletions

17
.gitignore vendored
View File

@ -39,22 +39,7 @@ Makefile.in
/src/matrix-version.h /src/matrix-version.h
/src/matrix-marshalers.[ch] /src/matrix-marshalers.[ch]
/src/stamp-matrix-marshalers /src/stamp-matrix-marshalers
/docs/reference/matrix-glib/version.xml /docs/valadoc/gtk-doc/gtk-doc
/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
# Vala related files # Vala related files
/src/Matrix-0.0.vapi /src/Matrix-0.0.vapi

View File

@ -3,8 +3,8 @@ ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS}
# Set up subdirectories to traverse # Set up subdirectories to traverse
SUBDIRS = src SUBDIRS = src
if ENABLE_GTK_DOC if ENABLE_DOCS
SUBDIRS += docs/reference/matrix-glib SUBDIRS += docs
endif endif
# Specify files to include in dist # Specify files to include in dist

View File

@ -93,21 +93,6 @@ if grep "^LT_INIT" "$coin" > /dev/null; then
fi fi
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 ..." echo "Running aclocal $aclocalinclude ..."
aclocal $m4dir $ACLOCAL_FLAGS $aclocalinclude || exit $? aclocal $m4dir $ACLOCAL_FLAGS $aclocalinclude || exit $?

View File

@ -94,6 +94,7 @@ GEE_REQUIRED=0.10.5
GIO_REQUIRED=2.22 GIO_REQUIRED=2.22
SOUP_REQUIRED=2.44.2 SOUP_REQUIRED=2.44.2
JSON_REQUIRED=0.16.2 JSON_REQUIRED=0.16.2
VALADOC_REQUIRED=0.3.1
# Check GLib # Check GLib
PKG_CHECK_MODULES([GLIB], PKG_CHECK_MODULES([GLIB],
@ -118,6 +119,52 @@ PKG_CHECK_MODULES([JSON], [json-glib-1.0 >= $JSON_REQUIRED])
# Check for GObject Introspection # Check for GObject Introspection
GOBJECT_INTROSPECTION_CHECK([1.32.0]) 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 debug=no
AC_ARG_ENABLE(debug, AC_ARG_ENABLE(debug,
AS_HELP_STRING([--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 # a new API, too
AC_SUBST([MATRIX_GLIB_API_VERSION], matrix_glib_api_version) 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_PATH_PROG([GLIB_GENMARSHAL], [glib-genmarshal])
AC_CONFIG_FILES([ AC_CONFIG_FILES([
Makefile Makefile
src/Makefile src/Makefile
src/matrix-version.h src/matrix-version.h
]) docs/Makefile
AM_COND_IF([ENABLE_GTK_DOC], [ docs/valadoc/Makefile
AC_CONFIG_FILES([ docs/valadoc/gtk-doc/Makefile
docs/reference/matrix-glib/version.xml
docs/reference/matrix-glib/Makefile
])
]) ])
AC_OUTPUT AC_OUTPUT
@ -174,5 +211,7 @@ AC_OUTPUT
echo "" echo ""
echo " Configuration summary for Matrix-$MATRIX_GLIB_VERSION" echo " Configuration summary for Matrix-$MATRIX_GLIB_VERSION"
echo " Installation prefix: $prefix" 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 " Debug: $debug"
echo "" echo ""

5
docs/Makefile.am Normal file
View File

@ -0,0 +1,5 @@
SUBDIRS =
if HAVE_VALADOC
SUBDIRS += valadoc
endif

5
docs/valadoc/Makefile.am Normal file
View File

@ -0,0 +1,5 @@
SUBDIRS =
if ENABLE_GTK_DOCS
SUBDIRS += gtk-doc
endif

View File

@ -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

View File

@ -18,28 +18,6 @@
#include "matrix-version.h" #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 gboolean
matrix_glib_check_version(guint required_major, matrix_glib_check_version(guint required_major,
guint required_minor, guint required_minor,

View File

@ -4,3 +4,14 @@ VALA_PKG_LIST = \
--pkg=libsoup-2.4 \ --pkg=libsoup-2.4 \
--pkg=gee-0.8 \ --pkg=gee-0.8 \
$(NULL) $(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)