doxygen/update-doxygen

   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
  22 set -e
  23
  24 if type doxygen > /dev/null 2>&1; then
  25         :
  26 else
  27         echo "doxygen/update-doxygen: 'doxygen' command not found." >&2
  28         echo "doxygen/update-doxygen: Skipping Doxygen docs generation." >&2
  29         exit 1
  30 fi
  31
  32 if 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
  38 fi
  39
  40 # Get the package version so that it can be included in the generated docs.
  41 PACKAGE_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.
  45 case $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                 ;;
 109 esac