From 1d72e45d85550dd00f99c3e50b762651a70f223f Mon Sep 17 00:00:00 2001 From: Tim Ruehsen Date: Wed, 2 Apr 2014 10:27:13 +0200 Subject: [PATCH] added GTKDOC support --- Makefile.am | 4 +- autogen.sh | 15 +++- configure.ac | 33 ++++++++ docs/libpsl/Makefile.am | 135 ++++++++++++++++++++++++++++++++ docs/libpsl/libpsl-docs.sgml | 37 +++++++++ docs/libpsl/libpsl-sections.txt | 17 ++++ 6 files changed, 238 insertions(+), 3 deletions(-) create mode 100644 docs/libpsl/Makefile.am create mode 100644 docs/libpsl/libpsl-docs.sgml create mode 100644 docs/libpsl/libpsl-sections.txt diff --git a/Makefile.am b/Makefile.am index be23856..073e4b3 100644 --- a/Makefile.am +++ b/Makefile.am @@ -1,10 +1,10 @@ # got some hints from https://gitorious.org/openismus-playground/examplelib/source -SUBDIRS = po include src tests data +SUBDIRS = po include src data docs/libpsl tests ACLOCAL_AMFLAGS = -I m4 ${ACLOCAL_FLAGS} # Enable GTK-Doc during make distcheck -#DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-man +DISTCHECK_CONFIGURE_FLAGS = --enable-gtk-doc --enable-man ## Install the generated pkg-config file (.pc) into the expected location for ## architecture-dependent package configuration information. Occasionally, diff --git a/autogen.sh b/autogen.sh index b279297..159a3c0 100755 --- a/autogen.sh +++ b/autogen.sh @@ -10,6 +10,15 @@ if test -z `which idn2`; then exit 1 fi +GTKDOCIZE=`which gtkdocize 2>/dev/null` +if test -z $GTKDOCIZE; then + echo "No gtk-doc support found. You can't build the docs." + echo "EXTRA_DIST =" >gtk-doc.make + echo "CLEANFILES =" >>gtk-doc.make +else + gtkdocize || exit $? +fi + mkdir m4 2>/dev/null autoreconf --install --force --symlink || exit $? @@ -19,5 +28,9 @@ echo "----------------------------------------------------------------" echo "Initialized build system. For a common configuration please run:" echo "----------------------------------------------------------------" echo -echo "./configure" +if test -z $GTKDOCIZE; then + echo "./configure" +else + echo "./configure --enable-gtk-doc" +fi echo diff --git a/configure.ac b/configure.ac index 9807e79..f10d2d8 100644 --- a/configure.ac +++ b/configure.ac @@ -18,6 +18,38 @@ m4_ifdef([AM_SILENT_RULES], [AM_SILENT_RULES([yes])]) AM_GNU_GETTEXT([external],[need-ngettext]) AM_GNU_GETTEXT_VERSION([0.18.1]) +# +# check for gtk-doc +# +m4_ifdef([GTK_DOC_CHECK], [ +GTK_DOC_CHECK([1.15],[--flavour no-tmpl]) +],[ +AM_CONDITIONAL([ENABLE_GTK_DOC], false) +]) + +# +# enable creation of man pages +# +AC_ARG_ENABLE(man,[AC_HELP_STRING([--enable-man], + [generate man pages [default=auto]])],enable_man=yes,enable_man=no) +AS_IF([test "$enable_man" != no], [ + AC_PATH_PROG([XSLTPROC], [xsltproc]) + AS_IF([test -z "$XSLTPROC"], [ + AS_IF([test "$enable_man" = yes], [ + AC_MSG_ERROR([xsltproc is required for --enable-man]) + ]) + enable_man=no + ]) +]) +AM_CONDITIONAL(ENABLE_MAN, test x$enable_man != xno) +AC_MSG_CHECKING([whether to generate man pages]) +AS_IF([ test "$enable_man" != no ], [ + AC_MSG_RESULT([yes]) +], [ + AC_MSG_RESULT([no]) +]) + + # Define these substitions here to keep all version information in one place. # For information on how to properly maintain the library version information, # refer to the libtool manual, section "Updating library version information": @@ -63,6 +95,7 @@ AC_CONFIG_FILES([Makefile include/Makefile src/Makefile po/Makefile.in + docs/libpsl/Makefile data/Makefile tests/Makefile libpsl-${LIBPSL_API_VERSION}.pc:libpsl.pc.in]) diff --git a/docs/libpsl/Makefile.am b/docs/libpsl/Makefile.am new file mode 100644 index 0000000..97279b5 --- /dev/null +++ b/docs/libpsl/Makefile.am @@ -0,0 +1,135 @@ +## 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=libpsl + +# Uncomment for versioned docs and specify the version of the module, e.g. '2'. +#DOC_MODULE_VERSION=2 + + +# The top-level SGML file. You can change this if you want to. +DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml + +# Directories containing the source code. +# gtk-doc will search all .c and .h files beneath these paths +# for inline comments documenting functions and macros. +# e.g. DOC_SOURCE_DIR=$(top_srcdir)/gtk $(top_srcdir)/gdk +DOC_SOURCE_DIR=$(top_srcdir)/src $(top_srcdir)/include + +# Extra options to pass to gtkdoc-scangobj. Not normally needed. +#SCANGOBJ_OPTIONS=--ignore-decorators="UNUSED_RESULT|CONST|PURE" + +# Extra options to supply to gtkdoc-scan. +# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +SCAN_OPTIONS=--ignore-decorators="G_GNUC_PSL_UNUSED" + +# Extra options to supply to gtkdoc-mkdb. +# e.g. MKDB_OPTIONS=--xml-mode --output-format=xml +MKDB_OPTIONS=--xml-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)/include/*.h +CFILE_GLOB=$(top_srcdir)/src/*.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 or dirs to ignore when scanning. Use base file/dir names +# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h private_code +IGNORE_HFILES=private.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= +GTKDOC_LIBS= + +# This includes the standard gtk-doc make rules, copied by gtkdocize. +include $(top_srcdir)/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 'make check' to test you doc status +# and run some sanity checks +if ENABLE_GTK_DOC +TESTS_ENVIRONMENT = cd $(srcdir) && \ + DOC_MODULE=$(DOC_MODULE) DOC_MAIN_SGML_FILE=$(DOC_MAIN_SGML_FILE) \ + SRCDIR=$(abs_srcdir) BUILDDIR=$(abs_builddir) +#TESTS = $(GTKDOC_CHECK) +endif + +-include $(top_srcdir)/git.mk + +theMANS = +man_MANS = + +if ENABLE_GTK_DOC +if ENABLE_MAN + +theMANS += libpsl.3 +man_MANS += docs $(theMANS) + +%.3: +#.xml.3: + @file=xml/`echo $@|cut -d'.' -f1`.xml; \ + @XSLTPROC@ -nonet http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $$file + +endif +endif + +BUILT_EXTRA_DIST = $(theMANS) +EXTRA_DIST += $(theMANS) +CLEANFILES ?= +CLEANFILES += $(theMANS) libpsl-overrides.txt libpsl-decl.txt libpsl-decl-list.txt + +clean-local: + rm -rf xml html + +dist-hook-local: all-local + +libpsl-docs-clean: clean + cd $(srcdir) && rm -rf xml html diff --git a/docs/libpsl/libpsl-docs.sgml b/docs/libpsl/libpsl-docs.sgml new file mode 100644 index 0000000..944cb03 --- /dev/null +++ b/docs/libpsl/libpsl-docs.sgml @@ -0,0 +1,37 @@ + + +]> + + + libpsl Reference Manual + + for libpsl [VERSION]. + The latest version of this documentation can be found on-line at + GitHub. + + + + + libpsl functions + + + + Object Hierarchy + + + + API Index + + + + Index of deprecated API + + + + + diff --git a/docs/libpsl/libpsl-sections.txt b/docs/libpsl/libpsl-sections.txt new file mode 100644 index 0000000..a795a1b --- /dev/null +++ b/docs/libpsl/libpsl-sections.txt @@ -0,0 +1,17 @@ +
+libpsl +Public Suffix List functions +psl_ctx_t +psl_free +psl_load_file +psl_load_fp +psl_builtin +psl_is_public +psl_unregistrable_domain +psl_registrable_domain +psl_suffix_count +psl_suffix_exception_count +psl_builtin_compile_time +psl_builtin_file_time +psl_builtin_sha1sum +