From 9480e3862d66c687958f249026738166b453c8c3 Mon Sep 17 00:00:00 2001 From: David Schleef Date: Mon, 7 Jun 2010 16:38:32 -0700 Subject: [PATCH] update gtk-doc --- doc/Makefile.am | 42 +++++++++++++++---- gtk-doc.make | 125 +++++++++++++++++++++++++++++++++++++++----------------- m4/gtk-doc.m4 | 26 +++++++++++- 3 files changed, 146 insertions(+), 47 deletions(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index 933bed4..d798fed 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -11,6 +11,10 @@ AUTOMAKE_OPTIONS = 1.6 # The name of the module, e.g. 'glib'. DOC_MODULE=orc +# 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 @@ -24,13 +28,20 @@ DOC_SOURCE_DIR=../orc SCANGOBJ_OPTIONS= # Extra options to supply to gtkdoc-scan. -# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED" +# 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= @@ -41,7 +52,11 @@ FIXXREF_OPTIONS= HFILE_GLOB=$(top_srcdir)/orc/*.h CFILE_GLOB=$(top_srcdir)/orc/*.c -# Header files to ignore when scanning. +# 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=orc-stdint.h @@ -53,12 +68,17 @@ HTML_IMAGES= # e.g. content_files=running.sgml building.sgml changes-2.0.sgml content_files=building.xml concepts.xml opcode_table.xml opcodes.xml table.xml +# 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. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) +# e.g. GTKDOC_CFLAGS=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS) # e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib) -INCLUDES= +GTKDOC_CFLAGS= GTKDOC_LIBS= # This includes the standard gtk-doc make rules, copied by gtkdocize. @@ -66,9 +86,17 @@ include $(top_srcdir)/gtk-doc.make # Other files to distribute # e.g. EXTRA_DIST += version.xml.in -EXTRA_DIST += +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 += -sync: - cd html && rsync -a . cooker.entropywave.com:/srv/code.entropywave.com/www/documentation/orc/ +# 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 +-include $(top_srcdir)/git.mk diff --git a/gtk-doc.make b/gtk-doc.make index 49cb12a..63adaed 100644 --- a/gtk-doc.make +++ b/gtk-doc.make @@ -5,11 +5,13 @@ #################################### 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) +GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) +GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = $(LIBTOOL) --mode=execute else GTKDOC_CC = $(CC) $(INCLUDES) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS) GTKDOC_LD = $(CC) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS) +GTKDOC_RUN = endif # We set GPATH here; this gives us semantics for GNU make @@ -29,7 +31,9 @@ EXTRA_DIST = \ $(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 + pdf-build.stamp \ + $(srcdir)/tmpl.stamp $(srcdir)/sgml.stamp $(srcdir)/html.stamp \ + $(srcdir)/pdf.stamp SCANOBJ_FILES = \ $(DOC_MODULE).args \ @@ -43,32 +47,45 @@ REPORT_FILES = \ $(DOC_MODULE)-undeclared.txt \ $(DOC_MODULE)-unused.txt -CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) xml/version.entities +CLEANFILES = $(SCANOBJ_FILES) $(REPORT_FILES) $(DOC_STAMPS) if ENABLE_GTK_DOC -all-local: html-build.stamp +if GTK_DOC_BUILD_HTML +HTML_BUILD_STAMP=html-build.stamp +else +HTML_BUILD_STAMP= +endif +if GTK_DOC_BUILD_PDF +PDF_BUILD_STAMP=pdf-build.stamp +else +PDF_BUILD_STAMP= +endif + +all-local: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) else all-local: endif -docs: html-build.stamp +docs: $(HTML_BUILD_STAMP) $(PDF_BUILD_STAMP) + +$(REPORT_FILES): sgml-build.stamp #### scan #### scan-build.stamp: $(HFILE_GLOB) $(CFILE_GLOB) @echo 'gtk-doc: Scanning header files' @-chmod -R u+w $(srcdir) - cd $(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) ; \ + @if grep -l '^..*$$' $(srcdir)/$(DOC_MODULE).types > /dev/null 2>&1 ; then \ + CC="$(GTKDOC_CC)" LD="$(GTKDOC_LD)" RUN="$(GTKDOC_RUN)" CFLAGS="$(GTKDOC_CFLAGS) $(CFLAGS)" LDFLAGS="$(GTKDOC_LIBS) $(LDFLAGS)" 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 + @touch scan-build.stamp $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE)-overrides.txt: scan-build.stamp @true @@ -78,26 +95,23 @@ $(DOC_MODULE)-decl.txt $(SCANOBJ_FILES) $(DOC_MODULE)-sections.txt $(DOC_MODULE) 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 + @cd $(srcdir) && gtkdoc-mktmpl --module=$(DOC_MODULE) $(MKTMPL_OPTIONS) + @touch tmpl-build.stamp tmpl.stamp: tmpl-build.stamp @true -tmpl/*.sgml: +$(srcdir)/tmpl/*.sgml: @true - #### xml #### -sgml-build.stamp: tmpl.stamp $(HFILE_GLOB) $(CFILE_GLOB) $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) +sgml-build.stamp: tmpl.stamp $(DOC_MODULE)-sections.txt $(srcdir)/tmpl/*.sgml $(expand_content_files) @echo 'gtk-doc: Building XML' @-chmod -R u+w $(srcdir) - cd $(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) - mkdir -p xml/ - cp version.entities xml/ - touch sgml-build.stamp + @touch sgml-build.stamp sgml.stamp: sgml-build.stamp @true @@ -107,13 +121,37 @@ sgml.stamp: sgml-build.stamp 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 ) + @rm -rf $(srcdir)/html + @mkdir $(srcdir)/html + @mkhtml_options=""; \ + gtkdoc-mkhtml 2>&1 --help | grep >/dev/null "\-\-path"; \ + if test "$(?)" = "0"; then \ + mkhtml_options=--path="$(srcdir)"; \ + fi; \ + cd $(srcdir)/html && gtkdoc-mkhtml $$mkhtml_options $(MKHTML_OPTIONS) $(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 + @cd $(srcdir) && gtkdoc-fixxref --module=$(DOC_MODULE) --module-dir=html --html-dir=$(HTML_DIR) $(FIXXREF_OPTIONS) + @touch html-build.stamp + +#### pdf #### + +pdf-build.stamp: sgml.stamp $(DOC_MAIN_SGML_FILE) $(content_files) + @echo 'gtk-doc: Building PDF' + @-chmod -R u+w $(srcdir) + @rm -rf $(srcdir)/$(DOC_MODULE).pdf + @mkpdf_imgdirs=""; \ + if test "x$(HTML_IMAGES)" != "x"; then \ + for img in $(HTML_IMAGES); do \ + part=`dirname $$img`; \ + echo $$mkpdf_imgdirs | grep >/dev/null "\-\-imgdir=$$part "; \ + if test $$? != 0; then \ + mkpdf_imgdirs="$$mkpdf_imgdirs --imgdir=$$part"; \ + fi; \ + done; \ + fi; \ + cd $(srcdir) && gtkdoc-mkpdf --path="$(abs_srcdir)" $$mkpdf_imgdirs $(DOC_MODULE) $(DOC_MAIN_SGML_FILE) $(MKPDF_OPTIONS) + @touch pdf-build.stamp ############## @@ -123,31 +161,43 @@ clean-local: distclean-local: cd $(srcdir) && \ - rm -rf xml $(REPORT_FILES) \ + rm -rf xml $(REPORT_FILES) $(DOC_MODULE).pdf \ $(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/*`; \ + @installfiles=`echo $(srcdir)/html/*`; \ if test "$$installfiles" = '$(srcdir)/html/*'; \ then echo '-- Nothing to install' ; \ else \ - $(mkinstalldirs) $(DESTDIR)$(TARGET_DIR); \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + $(mkinstalldirs) $${installdir} ; \ for i in $$installfiles; do \ echo '-- Installing '$$i ; \ - $(INSTALL_DATA) $$i $(DESTDIR)$(TARGET_DIR); \ + $(INSTALL_DATA) $$i $${installdir}; \ 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) ; \ + if test -n "$(DOC_MODULE_VERSION)"; then \ + mv -f $${installdir}/$(DOC_MODULE).devhelp2 \ + $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp2; \ + mv -f $${installdir}/$(DOC_MODULE).devhelp \ + $${installdir}/$(DOC_MODULE)-$(DOC_MODULE_VERSION).devhelp; \ + fi; \ + $(GTKDOC_REBASE) --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}; \ fi - uninstall-local: - rm -f $(DESTDIR)$(TARGET_DIR)/* + @if test -n "$(DOC_MODULE_VERSION)"; then \ + installdir="$(DESTDIR)$(TARGET_DIR)-$(DOC_MODULE_VERSION)"; \ + else \ + installdir="$(DESTDIR)$(TARGET_DIR)"; \ + fi; \ + rm -rf $${installdir} # # Require gtk-doc when making dist @@ -162,14 +212,13 @@ 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).pdf $(distdir)/ -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 + $(GTKDOC_REBASE) --online --relative --html-dir=$(distdir)/html .PHONY : dist-hook-local docs diff --git a/m4/gtk-doc.m4 b/m4/gtk-doc.m4 index bfdfa1d..2cfa1e7 100644 --- a/m4/gtk-doc.m4 +++ b/m4/gtk-doc.m4 @@ -8,6 +8,12 @@ AC_DEFUN([GTK_DOC_CHECK], [ AC_BEFORE([AC_PROG_LIBTOOL],[$0])dnl setup libtool first AC_BEFORE([AM_PROG_LIBTOOL],[$0])dnl setup libtool first + + dnl check for tools we added during development + AC_PATH_PROG([GTKDOC_CHECK],[gtkdoc-check]) + AC_PATH_PROGS([GTKDOC_REBASE],[gtkdoc-rebase],[true]) + AC_PATH_PROG([GTKDOC_MKPDF],[gtkdoc-mkpdf]) + dnl for overriding the documentation installation directory AC_ARG_WITH([html-dir], AS_HELP_STRING([--with-html-dir=PATH], [path to installed docs]),, @@ -26,14 +32,30 @@ AC_DEFUN([GTK_DOC_CHECK], [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]))]) + AC_MSG_ERROR([You need to have gtk-doc >= $1 installed to build $PACKAGE_NAME]))]) fi AC_MSG_CHECKING([whether to build gtk-doc documentation]) AC_MSG_RESULT($enable_gtk_doc) - AC_PATH_PROGS(GTKDOC_CHECK,gtkdoc-check,) + dnl enable/disable output formats + AC_ARG_ENABLE([gtk-doc-html], + AS_HELP_STRING([--enable-gtk-doc-html], + [build documentation in html format [[default=yes]]]),, + [enable_gtk_doc_html=yes]) + AC_ARG_ENABLE([gtk-doc-pdf], + AS_HELP_STRING([--enable-gtk-doc-pdf], + [build documentation in pdf format [[default=no]]]),, + [enable_gtk_doc_pdf=no]) + + if test -z "$GTKDOC_MKPDF"; then + enable_gtk_doc_pdf=no + fi + AM_CONDITIONAL([ENABLE_GTK_DOC], [test x$enable_gtk_doc = xyes]) + AM_CONDITIONAL([GTK_DOC_BUILD_HTML], [test x$enable_gtk_doc_html = xyes]) + AM_CONDITIONAL([GTK_DOC_BUILD_PDF], [test x$enable_gtk_doc_pdf = xyes]) AM_CONDITIONAL([GTK_DOC_USE_LIBTOOL], [test -n "$LIBTOOL"]) + AM_CONDITIONAL([GTK_DOC_USE_REBASE], [test -n "$GTKDOC_REBASE"]) ]) -- 2.7.4