[PATCH 1/8] Build documentation during build instead of dist

David Shea dshea at redhat.com
Fri Jul 25 21:08:21 UTC 2014


Gtk-doc is the worst at autotools integration. Allow me to enumerate:

  - It adds an option to our autoconf script that causes everything to
    fail if it is disabled. It is disabled by default.

  - It's driven through an opaque Makefile that forces docs to be built
    at source distribution time.

  - It requires the library to be built before it can generate docs, so
    it requires a full build before a source tarball can be created.

  - ...and it doesn't set up any Makefile dependencies at all, so it
    just fails if you forget to do a build first.

  - In fact, it's pretty crummy about keeping track of the dependencies
    for its own generated files. If you add or remove one of the source
    files that docs are generated from, you pretty much just have to do
    a git clean and start over.

  - It pulls in a ton of dist-time dependencies for other docs packages
    so that it can generate cross references but it still doesn't have
    cross reference data for half the stuff in glib because it sucks.

Get rid of gtk-doc's automatically installed files, where most of the
problems lie. Adapt the rules from gtk-doc.make into a single script
that runs everything to reduce the dependency nightmare. Run the script
at build time.
---
 .gitignore                |   1 -
 widgets/Makefile.am       |   2 +-
 widgets/autogen.sh        |   1 -
 widgets/configure.ac      |  10 ++--
 widgets/doc/Makefile.am   |  88 +++++++++++++++++++++++++++++++----
 widgets/doc/run-gtkdoc.sh | 116 ++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 201 insertions(+), 17 deletions(-)
 create mode 100755 widgets/doc/run-gtkdoc.sh

diff --git a/.gitignore b/.gitignore
index 1f46374..2b03149 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,7 +35,6 @@ configure
 data/liveinst/gnome/fedora-welcome.desktop
 depcomp
 dirbrowser
-gtk-doc.m4
 install-sh
 keymaps-override-*
 libtool
diff --git a/widgets/Makefile.am b/widgets/Makefile.am
index ad80f87..7afcf19 100644
--- a/widgets/Makefile.am
+++ b/widgets/Makefile.am
@@ -24,7 +24,7 @@ ACLOCAL_AMFLAGS = -I m4
 SUBDIRS = src python glade doc data
 
 MAINTAINERCLEANFILES = Makefile.in aclocal.m4 config.guess config.h.in config.sub \
-	configure depcomp gtk-doc.make install-sh ltmain.sh missing py-compile \
+	configure depcomp install-sh ltmain.sh missing py-compile \
 	m4/*.m4
 
 run-glade:
diff --git a/widgets/autogen.sh b/widgets/autogen.sh
index e18b17c..55ed5de 100755
--- a/widgets/autogen.sh
+++ b/widgets/autogen.sh
@@ -1,7 +1,6 @@
 #!/bin/bash -e
 [ -d m4 ] || mkdir m4
 libtoolize --copy --force
-gtkdocize --copy
 aclocal -I m4
 autoconf
 autoheader --force
diff --git a/widgets/configure.ac b/widgets/configure.ac
index 49c4104..ecad88f 100644
--- a/widgets/configure.ac
+++ b/widgets/configure.ac
@@ -47,10 +47,12 @@ GOBJECT_INTROSPECTION_CHECK([0.6.7])
 AS_IF([test "x$found_introspection" = xyes], [:],
       [AC_MSG_ERROR([*** GObject introspection must be enabled])])
 
-dnl A missing GTK_DOC_CHECK should fail in autogen.sh running gtkdocize, but
-dnl might as well check it here too
-m4_pattern_forbid([GTK_DOC_CHECK])dnl
-GTK_DOC_CHECK([1.14], [--flavour no-tmpl])
+# Add gtk-doc's html-dir option without pulling in the rest of gtk-doc
+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])
 
 PKG_CHECK_MODULES([GLADEUI], [gladeui-2.0 >= 3.10])
 PKG_CHECK_MODULES([GTK], [gtk+-x11-3.0 >= 3.11.3])
diff --git a/widgets/doc/Makefile.am b/widgets/doc/Makefile.am
index b148f39..d445d63 100644
--- a/widgets/doc/Makefile.am
+++ b/widgets/doc/Makefile.am
@@ -28,7 +28,7 @@ DOC_MODULE=AnacondaWidgets
 DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
 
 # Directories containing the source code.
-DOC_SOURCE_DIR=$(top_srcdir)
+DOC_SOURCE_DIR=$(top_srcdir)/src
 
 # Header files to ignore while scanning.
 IGNORE_HFILES = config.h \
@@ -46,14 +46,82 @@ MKDB_OPTIONS=--sgml-mode
 GTKDOC_CFLAGS=$(GLIB_CFLAGS) $(GTK_CFLAGS)
 GTKDOC_LIBS=$(GLIB_LIBS) $(GTK_LIBS) $(top_builddir)/src/libAnacondaWidgets.la
 
-include $(top_srcdir)/gtk-doc.make
+# Extra junk copied from gtk-doc.make
+GTKDOC_CC = $(LIBTOOL) --tag=CC --mode=compile $(CC) $(INCLUDES) $(GTKDOC_DEPS_CFLAGS) $(AM_CPPFLAGS) $(CPPFLAGS) $(AM_CFLAGS) $(CFLAGS)
+GTKDOC_LD = $(LIBTOOL) --tag=CC --mode=link $(CC) $(GTKDOC_DEPS_LIBS) $(AM_CFLAGS) $(CFLAGS) $(AM_LDFLAGS) $(LDFLAGS)
+GTKDOC_RUN = $(LIBTOOL) --mode=execute
 
-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
+# gtk-doc is terrible at integrating with autotools, so build things by hand.
 
-MAINTAINERCLEANFILES = AnacondaWidgets-overrides.txt AnacondaWidgets-sections.txt \
-	AnacondaWidgets.types Makefile.in
+# Copy the files we need into $builddir
+SETUP_FILES = $(DOC_MAIN_SGML_FILE)
+GTK_DOC_V_SETUP=$(GTK_DOC_V_SETUP_$(V))
+GTK_DOC_V_SETUP_=$(GTK_DOC_V_SETUP_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_SETUP_0=@echo " DOC   Preparing build";
+
+setup-build.stamp:
+	$(GTK_DOC_V_SETUP)if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+	    test -d $(abs_builddir) || $(MKDIR_P) $(abs_builddir) ; \
+            cp -pf $(abs_srcdir)/$(DOC_MAIN_SGML_FILE) $(abs_builddir)/$(DOC_MAIN_SGML_FILE) ; \
+        fi
+	$(AM_V_at)touch setup-build.stamp
+
+GTK_DOC_V_BUILD=$(GTK_DOC_V_BUILD_$(V))
+GTK_DOC_V_BUILD_=$(GTK_DOC_V_BUILD_$(AM_DEFAULT_VERBOSITY))
+GTK_DOC_V_BUILD_0=@echo "DOC   Building docs";
+
+noinst_DATA = gtkdoc.stamp
+dist_noinst_SCRIPTS = run-gtkdoc.sh
+dist_noinst_DATA = AnacondaWidgets-docs.xml
+
+# Copy a bunch of make variables to the environment and run the gtk-doc script
+gtkdoc.stamp: run-gtkdoc.sh $(DOC_SOURCE_DIR)/*.c $(DOC_SOURCE_DIR)/*.h \
+	      $(top_builddir)/src/libAnacondaWidgets.la \
+	      $(DOC_MAIN_SGML_FILE) \
+	      setup-build.stamp
+	$(GTK_DOC_V_BUILD)DOC_MODULE="$(DOC_MODULE)" \
+	DOC_MAIN_SGML_FILE="$(DOC_MAIN_SGML_FILE)" \
+	DOC_SOURCE_DIR="$(DOC_SOURCE_DIR)" \
+	IGNORE_HFILES="$(IGNORE_HFILES)" \
+	SCAN_OPTIONS="$(SCAN_OPTIONS)" \
+	MKDB_OPTIONS="$(MKDB_OPTIONS)" \
+	HTML_DIR="$(HTML_DIR)" \
+	GTKDOC_CC="$(GTKDOC_CC)" \
+	GTKDOC_LD="$(GTKDOC_LD)" \
+	GTKDOC_RUN="$(GTKDOC_RUN)" \
+	GTKDOC_CFLAGS="$(GTKDOC_CFLAGS)" \
+	GTKDOC_LIBS="$(GTKDOC_LIBS)" \
+	V=$(V) \
+	$(srcdir)/run-gtkdoc.sh
+
+# install and uninstall targets adapted from gtk-doc.make
+install-data-local: gtkdoc.stamp
+	@installfiles=`echo $(builddir)/html/*`; \
+        installdir="$(DESTDIR)$(HTML_DIR)/$(DOC_MODULE)" ; \
+	$(mkinstalldirs) $${installdir} ; \
+	for i in $$installfiles; do \
+	  echo ' $(INSTALL_DATA) '$$i ; \
+          $(INSTALL_DATA) $$i $${installdir}; \
+        done ; \
+	gtkdoc-rebase --relative --dest-dir=$(DESTDIR) --html-dir=$${installdir}
+
+uninstall-local:
+	@installdir="$(DESTDIR)$(HTML_DIR)/$(DOC_MODULE)" ; \
+	rm -rf $${installdir}
+
+# Clean up the mess
+CLEANFILES = AnacondaWidgets-decl-list.txt AnacondaWidgets-decl.txt \
+	     AnacondaWidgets-overrides.txt AnacondaWidgets-sections.txt \
+	     AnacondaWidgets.types AnacondaWidgets.args AnacondaWidgets.hierarchy \
+	     AnacondaWidgets.interfaces AnacondaWidgets.prerequisites AnacondaWidgets.signals \
+	     AnacondaWidgets-doc.bottom AnacondaWidgets-doc.top AnacondaWidgets-undeclared.txt \
+	     AnacondaWidgets-undocumented.txt AnacondaWidgets-unused.txt \
+	     sgml.stamp html.stamp gtkdoc.stamp setup-build.stamp
+
+clean-local:
+	@rm -rf xml html
+	@if test "$(abs_srcdir)" != "$(abs_builddir)" ; then \
+		rm -f $(abs_builddir)/$(DOC_MAIN_SGML_FILE) ; \
+	fi
+
+MAINTAINERCLEANFILES = Makefile.in
diff --git a/widgets/doc/run-gtkdoc.sh b/widgets/doc/run-gtkdoc.sh
new file mode 100755
index 0000000..40e6d1d
--- /dev/null
+++ b/widgets/doc/run-gtkdoc.sh
@@ -0,0 +1,116 @@
+#!/bin/sh -e
+# Generate HTML documentation
+#
+# Copyright (C) 2014  Red Hat, Inc.
+#
+# This copyrighted material is made available to anyone wishing to use,
+# modify, copy, or redistribute it subject to the terms and conditions of
+# the GNU General Public License v.2, or (at your option) any later version.
+# This program is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY expressed or implied, including the implied warranties of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.  You should have received a copy of the
+# GNU General Public License along with this program; if not, write to the
+# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+# 02110-1301, USA.  Any Red Hat trademarks that are incorporated in the
+# source code or documentation are not subject to the GNU General Public
+# License and may only be used or replicated with the express permission of
+# Red Hat, Inc.
+#
+# Red Hat Author(s): David Shea <dshea at redhat.com>
+#
+
+# Using make to run tools with multiple outputs is a recipe for disaster, so
+# use make to run this instead. It's not like any of it can be parallelized
+# anyway, and if anything changes we more than likely have to start at the
+# beginning. This script will run all of the various gtkdoc programs and create
+# a single output file, $DOC_OUTPUT_DIR/gtkdoc.stamp
+
+# ---- ENVIRONMENT VARIABLES -----
+# DOC_MODULE: the name of the module
+# DOC_MAIN_SGML_FILE: the top-level SGML file
+# DOC_SOURCE_DIR: directories containing the source code
+# IGNORE_HFILES: header files to ignore while scanning
+# SCAN_OPTIONS: Extra options to supply to gtkdoc-scan
+# MKDB_OPTIONS: Extra options to supply to gtkdoc-mkdb
+# HTML_DIR: The gtk-doc html directory
+# GTKDOC_CC: compiler to use with gtkdoc-scangobj (e.g., $(LTCOMPILE))
+# GTKDOC_LD: linker to use with gtkdoc-scangobj (e.g., $(LINK))
+# GTKDOC_RUN: Wrapper to run whatever gtdkco-scangobj made (e.g., $(LIBTOOL) --mode=execute)
+# GTKDOC_CFLAGS: CFLAGS to pass to gtkdoc-scangobj (e.g., $(GTK_CFLAGS))
+# GTKDOC_LIBS: LIBS to pass to gtkdoc-scangobj (e.g., $(GTK_LIB) plus the .la file to scan)
+
+# Everything will be output in the current directory because these tools are
+# awful at communicating paths to each other, and all of the paths in
+# $DOC_MAIN_SGML_FILE need to be relative to the output directory. Which
+# also means that $DOC_MAIN_SGML_FILE needs to be copied into $builddir.
+
+# This script should be run any time the source files or the main SGML file
+# change.
+
+if [ -n "$V" ]; then
+    set -x
+fi
+
+# Remove the old stamp file
+rm -f gtkdoc.stamp
+
+# Generate --source-dir args for gtkdoc-scan and gtkdoc-mkdb
+# Use realpath to convert to absolute paths because whoever wrote gtkdoc-mkdb
+# couldn't imagine a world in which input file aren't in the current directory
+_source_dir=
+for d in $DOC_SOURCE_DIR ; do
+    _source_dir="${_source_dir} --source-dir=$(realpath $d)"
+done
+
+# Convert DOC_MAIN_SGML_FILE to an absolute path because gtkdoc-mkhtml can't
+# specify an output directory
+DOC_MAIN_SGML_FILE=$(realpath ${DOC_MAIN_SGML_FILE})
+
+# Clean up files from gtkdoc-scan and run
+rm -f ${DOC_MODULE}-decl-list.txt ${DOC_MODULE}-decl.txt ${DOC_MODULE}-overrides.txt \
+      ${DOC_MODULE}-sections.txt ${DOC_MODULE}.types
+
+gtkdoc-scan \
+    --module=${DOC_MODULE} \
+    --ignore-headers="${IGNORE_HFILES}" ${_source_dir} \
+    --output-dir=. \
+    ${SCAN_OPTIONS}
+
+# Clean up files from gtkdoc-scangobj and run
+rm -f ${DOC_MODULE}.args ${DOC_MODULE}.hierarchy ${DOC_MODULE}.interfaces \
+      ${DOC_MODULE}.prerequisites ${DOC_MODULE}.signals
+
+gtkdoc-scangobj \
+    --module=${DOC_MODULE} \
+    --types=${DOC_MODULE}.types \
+    --output-dir=. \
+    --cc="${GTKDOC_CC}" \
+    --run="${GTKDOC_RUN}" \
+    --ld="${GTKDOC_LD}" \
+    --cflags="${GTKDOC_CFLAGS}" \
+    --ldflags="${GTKDOC_LIBS}"
+
+# Clean up files from gtkdoc-mkdb and run
+rm -rf ${DOC_MODULE}-doc.bottom ${DOC_MODULE}-doc.top \
+       ${DOC_MODULE}-undeclared.txt ${DOC_MODULE}-undocumented.txt \
+       ${DOC_MODULE}-unused.txt sgml.stamp xml
+
+gtkdoc-mkdb --module=${DOC_MODULE} \
+            --source-suffixes=c,h \
+            --ignore-files="${IGNORE_HFILES}" \
+            --output-dir=xml \
+            --main-sgml-file=${DOC_MAIN_SGML_FILE} \
+            --output-format=xml \
+            ${_source_dir} \
+            ${MKDB_OPTIONS}
+
+# We almost have something useful! gtkdoc-mkhtml is next
+rm -rf html
+mkdir html
+( cd html && gtkdoc-mkhtml ${DOC_MODULE} ${DOC_MAIN_SGML_FILE} )
+
+gtkdoc-fixxref --module=${DOC_MODULE} --module-dir=html --html-dir=${HTML_DIR}
+
+# All done, new stamp file
+touch gtkdoc.stamp
-- 
2.0.0



More information about the anaconda-patches mailing list