From 226b34727f14fafa2bc1564fcd19a66abb99648e Mon Sep 17 00:00:00 2001 From: Marcel Holtmann Date: Thu, 14 Aug 2008 22:59:09 +0200 Subject: Add infrastructure for gtk-doc support --- acinclude.m4 | 28 +++++++++ bootstrap-configure | 5 ++ configure.ac | 7 ++- doc/Makefile.am | 31 +++++++++- doc/bluez-docs.xml | 69 +++++++++++++++++++++ doc/gtk-doc.make | 173 ++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/version.xml.in | 1 + 7 files changed, 309 insertions(+), 5 deletions(-) create mode 100644 doc/bluez-docs.xml create mode 100644 doc/gtk-doc.make create mode 100644 doc/version.xml.in diff --git a/acinclude.m4 b/acinclude.m4 index 160c9464..2db14efb 100644 --- a/acinclude.m4 +++ b/acinclude.m4 @@ -10,6 +10,34 @@ AC_DEFUN([AC_PROG_CC_PIE], [ ]) ]) +AC_DEFUN([GTK_DOC_CHECK], [ + AC_ARG_WITH([html-dir], + AS_HELP_STRING([--with-html-dir=PATH], [path to installed docs]),, + [with_html_dir='${datadir}/gtk-doc/html']) + HTML_DIR="$with_html_dir" + AC_SUBST([HTML_DIR]) + + AC_ARG_ENABLE([gtk-doc], + AS_HELP_STRING([--enable-gtk-doc], [use gtk-doc to build documentation [[default=no]]]),, + [enable_gtk_doc=no]) + + if test x$enable_gtk_doc = xyes; then + ifelse([$1],[], + [PKG_CHECK_EXISTS([gtk-doc],, + AC_MSG_ERROR([gtk-doc not installed and --enable-gtk-doc requested]))], + [PKG_CHECK_EXISTS([gtk-doc >= $1],, + AC_MSG_ERROR([You need to have gtk-doc >= $1 installed to build gtk-doc]))]) + fi + + AC_MSG_CHECKING([whether to build gtk-doc documentation]) + AC_MSG_RESULT($enable_gtk_doc) + + AC_PATH_PROGS(GTKDOC_CHECK,gtkdoc-check,) + + AM_CONDITIONAL([ENABLE_GTK_DOC], [test x$enable_gtk_doc = xyes]) + AM_CONDITIONAL([GTK_DOC_USE_LIBTOOL], [test -n "$LIBTOOL"]) +]) + AC_DEFUN([AC_FUNC_PPOLL], [ AC_CHECK_FUNC(ppoll, dummy=yes, AC_DEFINE(NEED_PPOLL, 1, [Define to 1 if you need the ppoll() function.])) diff --git a/bootstrap-configure b/bootstrap-configure index ab7670fa..5ba74487 100755 --- a/bootstrap-configure +++ b/bootstrap-configure @@ -4,8 +4,13 @@ if [ -f config.status ]; then make maintainer-clean fi +if [ ! -f doc/gtk-doc.make ]; then + gtkdocize --copy --docdir doc +fi + ./bootstrap && \ ./configure --enable-maintainer-mode \ + --enable-gtk-doc \ --enable-debug \ --prefix=/usr \ --mandir=/usr/share/man \ diff --git a/configure.ac b/configure.ac index 10364b9e..7da3817d 100644 --- a/configure.ac +++ b/configure.ac @@ -22,6 +22,8 @@ m4_ifdef([AC_LIBTOOL_TAGS], [AC_LIBTOOL_TAGS([])]) AC_DISABLE_STATIC AC_PROG_LIBTOOL +GTK_DOC_CHECK + AC_FUNC_PPOLL AC_PATH_DBUS @@ -42,7 +44,6 @@ AC_OUTPUT([ gdbus/Makefile common/Makefile src/Makefile - doc/Makefile sbc/Makefile plugins/Makefile network/Makefile @@ -52,8 +53,10 @@ AC_OUTPUT([ tools/Makefile rfcomm/Makefile compat/Makefile + scripts/Makefile cups/Makefile test/Makefile - scripts/Makefile + doc/Makefile + doc/version.xml bluez.pc ]) diff --git a/doc/Makefile.am b/doc/Makefile.am index 5505391e..561741e7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,5 +1,30 @@ -EXTRA_DIST = manager-api.txt adapter-api.txt device-api.txt agent-api.txt \ - serial-api.txt network-api.txt input-api.txt audio-api.txt +DOC_MODULE = bluez + +DOC_MAIN_SGML_FILE = $(DOC_MODULE)-docs.xml + +DOC_SOURCE_DIR = ../src + +SCAN_OPTIONS = --rebuild-sections + +MKDB_OPTIONS = --sgml-mode --output-format=xml --tmpl-dir=. \ + --source-suffixes=c,h + +MKTMPL_OPTIONS = --output-dir=. -MAINTAINERCLEANFILES = Makefile.in +HFILE_GLOB = $(top_srcdir)/src/*.h +CFILE_GLOB = $(top_srcdir)/src/*.c + +IGNORE_HFILES = + +MAINTAINERCLEANFILES = Makefile.in \ + $(DOC_MODULE).types $(DOC_MODULE)-*.txt *.sgml + +if ENABLE_GTK_DOC +include $(top_srcdir)/doc/gtk-doc.make +else +EXTRA_DIST = $(DOC_MAIN_SGML_FILE) $(content_files) +endif + +EXTRA_DIST += manager-api.txt adapter-api.txt device-api.txt agent-api.txt \ + serial-api.txt network-api.txt input-api.txt audio-api.txt diff --git a/doc/bluez-docs.xml b/doc/bluez-docs.xml new file mode 100644 index 00000000..925ae427 --- /dev/null +++ b/doc/bluez-docs.xml @@ -0,0 +1,69 @@ + + +]> + + + BlueZ Reference Manual + Version &version; + + + Marcel + Holtmann + +
+ marcel@holtmann.org +
+ + + + + + 2002-2008 + Marcel Holtmann + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free + Documentation License, Version 1.1 or any later + version published by the Free Software Foundation with no + Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. You may obtain a copy of the GNU Free + Documentation License from the Free Software + Foundation by visiting their Web site or by writing + to: + +
+ The Free Software Foundation, Inc., + 59 Temple Place - Suite 330, + Boston, MA 02111-1307, + USA +
+ + + + + + API Reference + + + This part presents the function reference for BlueZ. + + + + + + License + + + + + + + Index + + diff --git a/doc/gtk-doc.make b/doc/gtk-doc.make new file mode 100644 index 00000000..354ffb7c --- /dev/null +++ b/doc/gtk-doc.make @@ -0,0 +1,173 @@ +# -*- mode: makefile -*- + +#################################### +# Everything below here is generic # +#################################### + +if GTK_DOC_USE_LIBTOOL +GTKDOC_CC = $(LIBTOOL) --mode=compile $(CC) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --mode=link $(CC) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +else +GTKDOC_CC = $(CC) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(CC) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +endif + +# We set GPATH here; this gives us semantics for GNU make +# which are more like other make's VPATH, when it comes to +# whether a source that is a target of one rule is then +# searched for in VPATH/GPATH. +# +GPATH = $(srcdir) + +TARGET_DIR=$(HTML_DIR)/$(DOC_MODULE) + +EXTRA_DIST = \ + $(content_files) \ + $(HTML_IMAGES) \ + $(DOC_MAIN_SGML_FILE) \ + $(DOC_MODULE)-sections.txt \ + $(DOC_MODULE)-overrides.txt + +DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \ + $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp + +SCANOBJ_FILES = \ + $(DOC_MODULE).args \ + $(DOC_MODULE).hierarchy \ + $(DOC_MODULE).interfaces \ + $(DOC_MODULE).prerequisites \ + $(DOC_MODULE).signals + +REPORT_FILES = \ + $(DOC_MODULE)-undocumented.txt \ + $(DOC_MODULE)-undeclared.txt \ + $(DOC_MODULE)-unused.txt + +CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) + +if ENABLE_GTK_DOC +all-local: html-build.stamp +else +all-local: +endif + +docs: html-build.stamp + +#### scan #### + +scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) + @echo 'gtk-doc: Scanning header files' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && \ + gtkdoc-scan --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --ignore-headers="$(IGNORE_HFILES)" $(SCAN_OPTIONS) $(EXTRA_HFILES) + if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null 2>&1 ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" CFLAGS="$(GTKDOC_CFLAGS)" LDFLAGS="$(GTKDOC_LIBS)" gtkdoc-scangobj $(SCANGOBJ_OPTIONS) --module=$(DOC_MODULE) --output-dir=$(srcdir) ; \ + else \ + cd $(srcdir) ; \ + for i in $(SCANOBJ_FILES) ; do \ + test -f $$i || touch $$i ; \ + done \ + fi + touch scan-build.stamp + +$(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp + @true + +#### templates #### + +tmpl-build.stamp: $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt + @echo 'gtk-doc: Rebuilding template files' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) + touch tmpl-build.stamp + +tmpl.stamp: tmpl-build.stamp + @true + +tmpl/*.sgml: + @true + + +#### xml #### + +sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) + @echo 'gtk-doc: Building XML' + @-chmod -R u+w $(srcdir) + cd $(srcdir) && \ + gtkdoc-mkdb --module=$(DOC_MODULE) --source-dir=$(DOC_SOURCE_DIR) --output-format=xml --expand-content-files="$(expand_content_files)" --main-sgml-file=$(DOC_MAIN_SGML_FILE) $(MKDB_OPTIONS) + touch sgml-build.stamp + +sgml.stamp: sgml-build.stamp + @true + +#### html #### + +html-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + @echo 'gtk-doc: Building HTML' + @-chmod -R u+w $(srcdir) + rm -rf $(srcdir)/html + mkdir $(srcdir)/html + cd $(srcdir)/html && gtkdoc-mkhtml $(DOC_MODULE) ../$(DOC_MAIN_SGML_FILE) + test "x$(HTML_IMAGES)" = "x" || ( cd $(srcdir) && cp $(HTML_IMAGES) html ) + @echo 'gtk-doc: Fixing cross-references' + cd $(srcdir) && gtkdoc-fixxref --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + touch html-build.stamp + +############## + +clean-local: + rm -f *~ *.bak + rm -rf .libs + +distclean-local: + cd $(srcdir) && \ + rm -rf xml $(REPORT_FILES) \ + $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt + +maintainer-clean-local: clean + cd $(srcdir) && rm -rf xml html + +install-data-local: + -installfiles=`echo $(srcdir)/html/*`; \ + if test "$$installfiles" = '$(srcdir)/html/*'; \ + then echo '-- Nothing to install' ; \ + else \ + $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR); \ + for i in $$installfiles; do \ + echo '-- Installing '$$i ; \ + $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + done; \ + echo '-- Installing $(srcdir)/html/index.sgml' ; \ + $(INSTALL_DATA) $(srcdir)/html/index.sgml $(DESTDIR)$(TARGET_DIR) || :; \ + which gtkdoc-rebase >/dev/null && \ + gtkdoc-rebase --relative --dest-dir=$(DESTDIR) --html-dir=$(DESTDIR)$(TARGET_DIR) ; \ + fi + + +uninstall-local: + rm -f $(DESTDIR)$(TARGET_DIR)/* + +# +# Require gtk-doc when making dist +# +if ENABLE_GTK_DOC +dist-check-gtkdoc: +else +dist-check-gtkdoc: + @echo "*** gtk-doc must be installed and enabled in order to make dist" + @false +endif + +dist-hook: dist-check-gtkdoc dist-hook-local + mkdir $(distdir)/tmpl + mkdir $(distdir)/xml + mkdir $(distdir)/html + -cp $(srcdir)/tmpl/*.sgml $(distdir)/tmpl + -cp $(srcdir)/xml/*.xml $(distdir)/xml + cp $(srcdir)/html/* $(distdir)/html + -cp $(srcdir)/$(DOC_MODULE).types $(distdir)/ + -cp $(srcdir)/$(DOC_MODULE)-sections.txt $(distdir)/ + cd $(distdir) && rm -f $(DISTCLEANFILES) + -gtkdoc-rebase --online --relative --html-dir=$(distdir)/html + +.PHONY : dist-hook-local docs diff --git a/doc/version.xml.in b/doc/version.xml.in new file mode 100644 index 00000000..d78bda93 --- /dev/null +++ b/doc/version.xml.in @@ -0,0 +1 @@ +@VERSION@ -- cgit