doxygen/update-doxygen

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