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.
This commit is contained in:
Jia Tan 2023-03-16 21:35:55 +08:00
parent b1216a7772
commit 1321852a3b
2 changed files with 112 additions and 0 deletions

View File

@ -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-`; \

111
doxygen/update-doxygen Executable file
View File

@ -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