GNOME.org
 

[gegl-gtk] Documentation: Add gtk-doc based API reference to build

commit c33f2a6a6ad79e66a05b7ef3d2f56f4937d946fb
Author: Jon Nordby <jononor gmail com>
Date:   Wed Sep 21 00:38:41 2011 +0200

    Documentation: Add gtk-doc based API reference to build
    
    Also update README

 Makefile.am                |   36 +++++++++++++++
 README                     |    3 +-
 autogen.sh                 |   48 +++-----------------
 configure.ac               |   10 +---
 docs/.gitignore            |    1 +
 docs/reference/.gitignore  |    6 +++
 docs/reference/Makefile.am |  103 ++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 158 insertions(+), 49 deletions(-)
---
diff --git a/Makefile.am b/Makefile.am
index f0ddf69..3f5e2d7 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -19,6 +19,7 @@ endif
 EXTRA_DIST = \
 	$(built_dist_files) \
 	autogen.sh \
+	docs/gtk-doc.make \
 	gegl-gtk2-0.1.pc.in \
 	gegl-gtk3-0.1.pc.in \
 	m4/introspection.m4
@@ -27,3 +28,38 @@ DISTCHECK_CONFIGURE_FLAGS = --enable-introspection
 
 DISTCLEANFILES = \
 	$(built_dist_files)
+
+# Documentation
+gtkdoc_builddir=$(top_builddir)/docs/reference/
+gtkdoc_distdir=$(top_distdir)/docs/reference/
+gtkdoc_srcdir=$(top_srcdir)/docs/reference/
+
+all-local: $(noinst_LTLIBRARIES)
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) all
+
+clean-local:
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) clean
+	rm -f src/*.stamp src/*.tmp
+
+distclean-local:
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) distclean
+
+docs: $(noinst_LTLIBRARIES)
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) docs
+
+install-data-local:
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) install-data
+
+uninstall-local:
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) uninstall
+
+dist-hook:
+	mkdir -p $(gtkdoc_distdir)
+	cp $(gtkdoc_srcdir)/Makefile.am $(gtkdoc_srcdir)/Makefile.in $(gtkdoc_distdir)
+	cd $(gtkdoc_builddir) && $(MAKE) $(AM_MAKEFLAGS) \
+	distdir="../../$(gtkdoc_distdir)" \
+	top_distdir="../../$(top_distdir)" \
+	dist-hook
+
+.PHONY: docs
+# End Documentation
diff --git a/README b/README
index 36d9cc6..40e44da 100644
--- a/README
+++ b/README
@@ -48,8 +48,7 @@ Need to build and work with whatever is the latest Gegl release.
 
 * Sanitize coding style
 * API review, check naming
-* Change translation properties (x,y) to take floats
-* Add new() and set_input_node() methods to GeglView
+* Complete API documentation
 * Simple examples for all provided features
 
 * Register display operation in a generic way with GEGL (needs work in GEGL)
diff --git a/autogen.sh b/autogen.sh
index be86299..02cabc2 100755
--- a/autogen.sh
+++ b/autogen.sh
@@ -117,35 +117,6 @@ if test x$LIBTOOLIZE != x; then
     check_version $VER $LIBTOOL_REQUIRED_VERSION true || DIE=1
 fi
 
-# check if gtk-doc is explicitely disabled
-#for ag_option in $AUTOGEN_CONFIGURE_ARGS $@
-#do
-#  case $ag_option in
-#    -disable-gtk-doc | --disable-gtk-doc)
-#    enable_gtk_doc=no
-#  ;;
-#  esac
-#done
-
-#if test x$enable_gtk_doc = xno; then
-#  echo "skipping test for gtkdocize"
-#else
-#  echo -n "checking for gtkdocize ... "
-#  if (gtkdocize --version) < /dev/null > /dev/null 2>&1; then
-#      echo "yes"
-#  else
-#      echo
-#      echo "  You must have gtk-doc installed to compile $PROJECT."
-#      echo "  Install the appropriate package for your distribution,"
-#      echo "  or get the source tarball at"
-#      echo "  http://ftp.gnome.org/pub/GNOME/sources/gtk-doc/";
-#      echo "  You can also use the option --disable-gtk-doc to skip"
-#      echo "  this test but then you will not be able to generate a"
-#      echo "  configure script that can build the API documentation."
-#      DIE=1
-#  fi
-#fi
-
 echo -n "checking for autoconf >= $AUTOCONF_REQUIRED_VERSION ... "
 if ($AUTOCONF --version) < /dev/null > /dev/null 2>&1; then
     VER=`$AUTOCONF --version | head -n 1 \
@@ -247,17 +218,14 @@ fi
 
 $LIBTOOLIZE --force || exit $?
 
-#if test x$enable_gtk_doc = xno; then
-#    if test -f gtk-doc.make; then :; else
-#       echo "EXTRA_DIST = missing-gtk-doc" > gtk-doc.make
-#    fi
-#    echo "WARNING: You have disabled gtk-doc."
-#    echo "         As a result, you will not be able to generate the API"
-#    echo "         documentation and 'make dist' will not work."
-#    echo
-#else
-#    gtkdocize || exit $?
-#fi
+if test x$enable_gtk_doc = xno; then
+    echo "WARNING: You have disabled gtk-doc."
+    echo "         As a result, you will not be able to generate the API"
+    echo "         documentation and 'make dist' will not work."
+    echo
+else
+    gtkdocize --copy --docdir docs --flavour no-tmpl || exit $?
+fi
 
 # optionally feature autoheader
 ($AUTOHEADER --version)  < /dev/null > /dev/null 2>&1 && $AUTOHEADER || exit 1
diff --git a/configure.ac b/configure.ac
index d12ffd2..1faeb94 100644
--- a/configure.ac
+++ b/configure.ac
@@ -172,12 +172,6 @@ fi
 
 AC_C_RESTRICT
 
-dnl disable docs generation.
-AC_ARG_ENABLE([docs],
-              [  --disable-docs          disable docs generation (default=no)],,
-              enable_docs="yes")
-
-AM_CONDITIONAL(ENABLE_DOCS, test "x$enable_docs" = "xyes")
 
 ######################################
 # Checks for BABL
@@ -262,7 +256,7 @@ AM_CONDITIONAL(HAVE_VALA, test "$have_vala" = "yes")
 # Checks for gtk-doc and docbook-tools
 ######################################
 
-GTK_DOC_CHECK([1.0])
+GTK_DOC_CHECK([1.0], [--docdir docs --flavour no-tmpl])
 
 dnl NOTE: We need to use a separate automake conditional for this
 dnl   	  to make this work with the tarballs.
@@ -313,6 +307,7 @@ gegl-gtk/Makefile
 operations/Makefile
 examples/Makefile
 tests/Makefile
+docs/reference/Makefile
 gegl-gtk2-0.1.pc
 gegl-gtk3-0.1.pc
 ])
@@ -322,6 +317,7 @@ AC_MSG_RESULT([
 Building GEGL with prefix=$prefix
 
   GTK+ version:           $have_gtk
+  Documentation:          $enable_gtk_doc
   GObject Introspection:  $enable_introspection
   Vala support:           $have_vala
 ]);
diff --git a/docs/.gitignore b/docs/.gitignore
new file mode 100644
index 0000000..f00f8e8
--- /dev/null
+++ b/docs/.gitignore
@@ -0,0 +1 @@
+gtk-doc.make
diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore
new file mode 100644
index 0000000..f7f93b5
--- /dev/null
+++ b/docs/reference/.gitignore
@@ -0,0 +1,6 @@
+html/*
+xml/*
+*.in
+gegl-gtk*
+*.stamp
+Makefile
diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
new file mode 100644
index 0000000..3f659a2
--- /dev/null
+++ b/docs/reference/Makefile.am
@@ -0,0 +1,103 @@
+## Process this file with automake to produce Makefile.in
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# 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=gegl-gtk
+
+# Uncomment for versioned docs and specify the version of the module, e.g. '2'.
+DOC_MODULE_VERSION=$(GEGL_GTK_VERSION)
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# Rule for generating DOC_MAIN_SGML_FILE
+sgml.stamp: $(DOC_MODULE)-sections.txt
+$(DOC_MAIN_SGML_FILE): sgml.stamp
+
+# Directories containing the source code, relative to $(srcdir).
+# gtk-doc will search all .c and .h files beneath these paths
+# for inline comments documenting functions and macros.
+# e.g. DOC_SOURCE_DIR=../../../gtk ../../../gdk
+DOC_SOURCE_DIR=$(top_srcdir)/gegl-gtk
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+# 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
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkhtml
+MKHTML_OPTIONS=
+
+# 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=
+
+# 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)/gegl-gtk/*.h
+CFILE_GLOB=$(top_srcdir)/gegl-gtk/*.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=
+
+# Header files to ignore when scanning. Use base file name, no paths
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES=config.h
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+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=
+
+# 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=
+
+# 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. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_CFLAGS = $(GTK_CFLAGS) $(GEGL_CFLAGS)
+GTKDOC_LIBS = $(top_builddir)/gegl-gtk/libgegl-gtk GEGL_GTK_GTK_VERSION@- GEGL_GTK_API_VERSION@.la $(GTK_LIBS) $(GEGL_LIBS)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/docs/gtk-doc.make
+
+# Other files to distribute
+# e.g. EXTRA_DIST += version.xml.in
+EXTRA_DIST +=
+
+# 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
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]