1#!/bin/sh 2# SPDX-License-Identifier: 0BSD 3 4############################################################################# 5# 6# Updates the Doxygen generated documentation files in the source tree. 7# If the doxygen command is not installed, it will exit with an error. 8# This script can generate Doxygen documentation for all source files or for 9# just liblzma API header files. 10# 11# It is recommended to use this script to update the Doxygen-generated HTML 12# files since this will include the package version in the output and, 13# in case of liblzma API docs, strip JavaScript files from the output. 14# 15############################################################################# 16# 17# Authors: Jia Tan 18# Lasse Collin 19# 20############################################################################# 21 22set -e 23 24if type doxygen > /dev/null 2>&1; then 25 : 26else 27 echo "doxygen/update-doxygen: 'doxygen' command not found." >&2 28 echo "doxygen/update-doxygen: Skipping Doxygen docs generation." >&2 29 exit 1 30fi 31 32if test ! -f Doxyfile; then 33 cd `dirname "$0"` || exit 1 34 if test ! -f Doxyfile; then 35 echo "doxygen/update-doxygen: Cannot find Doxyfile" >&2 36 exit 1 37 fi 38fi 39 40# Get the package version so that it can be included in the generated docs. 41PACKAGE_VERSION=`cd .. && sh build-aux/version.sh` || exit 1 42 43# If no arguments are specified, default to generating liblzma API header 44# documentation only. 45case $1 in 46 '' | api) 47 # Remove old documentation before re-generating the new. 48 rm -rf ../doc/api 49 50 # Generate the HTML documentation by preparing the Doxyfile 51 # in stdin and piping the result to the doxygen command. 52 # With Doxygen, the last assignment of a value to a tag will 53 # override any earlier assignment. So, we can use this 54 # feature to override the tags that need to change between 55 # "api" and "internal" modes. 56 ( 57 cat Doxyfile 58 echo "PROJECT_NUMBER = $PACKAGE_VERSION" 59 ) | doxygen - 60 61 # As of Doxygen 1.8.0 - 1.9.6 and the Doxyfile options we use, 62 # the output is good without any JavaScript. Unfortunately 63 # Doxygen doesn't have an option to disable JavaScript usage 64 # completely so we strip it away with the hack below. 65 # 66 # Omitting the JavaScript code avoids some license hassle 67 # as jquery.js is fairly big, it contains more than jQuery 68 # itself, and doesn't include the actual license text (it 69 # only refers to the MIT license by name). 70 echo "Stripping JavaScript from Doxygen output..." 71 for F in ../doc/api/*.html 72 do 73 sed 's/<script [^>]*><\/script>//g 74 s/onclick="[^"]*"//g' \ 75 "$F" > ../doc/api/tmp 76 mv -f ../doc/api/tmp "$F" 77 done 78 rm -f ../doc/api/*.js 79 ;; 80 81 internal) 82 # The docs from internal aren't for distribution so 83 # the JavaScript files aren't an issue here. 84 rm -rf ../doc/internal 85 ( 86 cat Doxyfile 87 echo "PROJECT_NUMBER = $PACKAGE_VERSION" 88 echo 'PROJECT_NAME = "XZ Utils"' 89 echo 'STRIP_FROM_PATH = ../src' 90 echo 'INPUT = ../src' 91 echo 'HTML_OUTPUT = internal' 92 echo 'EXTRACT_PRIVATE = YES' 93 echo 'EXTRACT_STATIC = YES' 94 echo 'EXTRACT_LOCAL_CLASSES = YES' 95 echo 'SEARCHENGINE = YES' 96 ) | doxygen - 97 ;; 98 99 *) 100 echo "doxygen/update-doxygen: Error: mode argument '$1'" \ 101 "is not supported." >&2 102 echo "doxygen/update-doxygen: Supported modes:" >&2 103 echo "doxygen/update-doxygen: - 'api' (default):" \ 104 "liblzma API docs into doc/api" >&2 105 echo "doxygen/update-doxygen: - 'internal':"\ 106 "internal docs into doc/internal" >&2 107 exit 1 108 ;; 109esac 110