Build: Create doxygen/update-doxygen script.

This is a helper script to generate the Doxygen documentation. It can be
run in 'liblzma' or 'internal' mode by setting the first argument. It
will default to 'liblzma' mode and only generate documentation for the
liblzma API header files.

The helper script will be run during the custom mydist hook when we
create releases. This hook already alters the source directory, so its
fine to do it here too. This way, we can include the Doxygen generated
files in the distrubtion and when installing.

In 'liblzma' mode, the JavaScript is stripped from the .html files and
the .js files are removed. This avoids license hassle from jQuery and
other libraries that Doxygen 1.9.6 puts into jquery.js in minified form.

2 files changed, 112 insertions, 0 deletions

diff --git a/Makefile.am b/Makefile.am
index 0df658f..6d52e0f 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -124,6 +124,7 @@ dist-hook:
 mydist:
 	sh "$(srcdir)/src/liblzma/validate_map.sh"
 	cd "$(srcdir)/po4a" && sh update-po
+	cd "$(srcdir)/doxygen" && sh update-doxygen
 	VERSION=$(VERSION); \
 	if test -d "$(srcdir)/.git" && type git > /dev/null 2>&1; then \
 		SNAPSHOT=`cd "$(srcdir)" && git describe --abbrev=4 | cut -b2-`; \
diff --git a/doxygen/update-doxygen b/doxygen/update-doxygen
new file mode 100755
index 0000000..e5f3ab4
--- /dev/null
+++ b/doxygen/update-doxygen
@@ -0,0 +1,111 @@
+#!/bin/sh
+#
+#############################################################################
+#
+# Updates the Doxygen generated documentation files in the source tree.
+# If the doxygen command is not installed, it will exit with an error.
+# This script can generate Doxygen documentation for all source files or for
+# just liblzma API header files.
+#
+# It is recommended to use this script to update the Doxygen-generated HTML
+# files since this will include the package version in the output and,
+# in case of liblzma API docs, strip JavaScript files from the output.
+#
+#############################################################################
+#
+# Authors: Jia Tan
+#          Lasse Collin
+#
+# This file has been put into the public domain.
+# You can do whatever you want with this file.
+#
+#############################################################################
+
+set -e
+
+if type doxygen > /dev/null 2>&1; then
+	:
+else
+	echo "doxygen/update-doxygen: 'doxygen' command not found." >&2
+	echo "doxygen/update-doxygen: Skipping Doxygen docs generation." >&2
+	exit 1
+fi
+
+if test ! -f Doxyfile; then
+	cd `dirname "$0"` || exit 1
+	if test ! -f Doxyfile; then
+		echo "doxygen/update-doxygen: Cannot find Doxyfile" >&2
+		exit 1
+	fi
+fi
+
+# Get the package version so that it can be included in the generated docs.
+PACKAGE_VERSION=`cd .. && sh build-aux/version.sh` || exit 1
+
+# If no arguments are specified, default to generating liblzma API header
+# documentation only.
+case $1 in
+	'' | liblzma)
+		# Remove old documentation before re-generating the new.
+		rm -rf ../doc/liblzma
+
+		# Generate the HTML documentation by preparing the Doxyfile
+		# in stdin and piping the result to the doxygen command.
+		# With Doxygen, the last assignment of a value to a tag will
+		# override any earlier assignment. So, we can use this
+		# feature to override the tags that need to change between
+		# "liblzma" and "internal" modes.
+		(
+			cat Doxyfile
+			echo "PROJECT_NUMBER         = $PACKAGE_VERSION"
+		) | doxygen -
+
+		# As of Doxygen 1.8.0 - 1.9.6 and the Doxyfile options we use,
+		# the output is good without any JavaScript. Unfortunately
+		# Doxygen doesn't have an option to disable JavaScript usage
+		# completely so we strip it away with the hack below.
+		#
+		# Omitting the JavaScript code avoids some license hassle
+		# as jquery.js is fairly big, it contains more than jQuery
+		# itself, and doesn't include the actual license text (it
+		# only refers to the MIT license by name).
+		echo "Stripping JavaScript from Doxygen output..."
+		for F in ../doc/liblzma/*.html
+		do
+			sed 's/<script [^>]*><\/script>//g
+				s/onclick="[^"]*"//g' \
+				"$F" > ../doc/liblzma/tmp
+			mv -f ../doc/liblzma/tmp "$F"
+		done
+		rm -f ../doc/liblzma/*.js
+		;;
+
+	internal)
+		# The docs from internal aren't for distribution so
+		# the JavaScript files aren't an issue here.
+		rm -rf ../doc/internal
+		(
+			cat Doxyfile
+			echo "PROJECT_NUMBER         = $PACKAGE_VERSION"
+			echo 'PROJECT_NAME           = "XZ Utils"'
+			echo 'STRIP_FROM_PATH        = ../src'
+			echo 'INPUT                  = ../src'
+			echo 'HTML_OUTPUT            = internal'
+			echo 'EXTRACT_PRIVATE        = YES'
+			echo 'EXTRACT_STATIC         = YES'
+			echo 'EXTRACT_LOCAL_CLASSES  = YES'
+			echo 'SEARCHENGINE           = YES'
+		) | doxygen -
+		;;
+
+	*)
+		echo "doxygen/update-doxygen: Error: mode argument '$1'" \
+			"is not supported." >&2
+		echo "doxygen/update-doxygen: Supported modes:" >&2
+		echo "doxygen/update-doxygen: - 'liblzma' (default):" \
+			"API docs into doc/liblzma" >&2
+		echo "doxygen/update-doxygen: - 'internal':"\
+			"internal docs into doc/internal" >&2
+		exit 1
+		;;
+esac