doxygen/update-doxygen

   1 #!/bin/sh
   2 # SPDX-License-Identifier: 0BSD
   3
   4 #############################################################################
   5 #
   6 # While it's possible to use the Doxyfile as is to generate liblzma API
   7 # documentation, it is recommended to use this script because this adds
   8 # the XZ Utils version number to the generated HTML.
   9 #
  10 # Other features:
  11 #  - Generate documentation of the XZ Utils internals.
  12 #  - Set input and output paths for out-of-tree builds.
  13 #
  14 #############################################################################
  15 #
  16 # Authors: Jia Tan
  17 #          Lasse Collin
  18 #
  19 #############################################################################
  20
  21 set -e
  22
  23 show_usage()
  24 {
  25         echo "Usage: $0 <api|internal> [ABS_TOP_SRCDIR ABS_OUTDIR]"
  26         echo
  27         echo "Supported modes:"
  28         echo " - 'api' (default): liblzma API docs into doc/api"
  29         echo " - 'internal': internal docs into doc/internal"
  30         echo
  31         echo "Absolute source and output dirs may be set" \
  32                 "to do an out-of-tree build."
  33         echo "The output directory must already exist."
  34         exit 1
  35 }
  36
  37 case $1 in
  38         api|internal)
  39                 ;;
  40         *)
  41                 show_usage
  42                 ;;
  43 esac
  44
  45 if type doxygen > /dev/null 2>&1; then
  46         :
  47 else
  48         echo "$0: 'doxygen' command not found" >&2
  49         exit 1
  50 fi
  51
  52 case $# in
  53         1)
  54                 # One argument: Building inside the source tree
  55                 ABS_TOP_SRCDIR=`dirname "$0"`/..
  56                 ABS_OUTDIR=$ABS_TOP_SRCDIR/doc
  57                 ;;
  58         3)
  59                 # Three arguments: Possibly an out of tree build
  60                 ABS_TOP_SRCDIR=$2
  61                 ABS_OUTDIR=$3
  62                 ;;
  63         *)
  64                 show_usage
  65                 ;;
  66 esac
  67
  68 if test ! -f "$ABS_TOP_SRCDIR/doxygen/Doxyfile"; then
  69         echo "$0: Source dir '$ABS_TOP_SRCDIR/doxygen/Doxyfile' not found" >&2
  70         exit 1
  71 fi
  72 if test ! -d "$ABS_OUTDIR"; then
  73         echo "$0: Output dir '$ABS_OUTDIR' not found" >&2
  74         exit 1
  75 fi
  76
  77 # Get the package version so that it can be included in the generated docs.
  78 PACKAGE_VERSION=`cd "$ABS_TOP_SRCDIR" && sh build-aux/version.sh`
  79
  80 case $1 in
  81         api)
  82                 # Remove old documentation before re-generating the new.
  83                 rm -rf "$ABS_OUTDIR/api"
  84
  85                 # Generate the HTML documentation by preparing the Doxyfile
  86                 # in stdin and piping the result to the doxygen command.
  87                 # With Doxygen, the last assignment of a value to a tag will
  88                 # override any earlier assignment. So, we can use this
  89                 # feature to override the tags that need to change between
  90                 # "api" and "internal" modes.
  91                 ABS_SRCDIR=$ABS_TOP_SRCDIR/src/liblzma/api
  92                 (
  93                         cat "$ABS_TOP_SRCDIR/doxygen/Doxyfile"
  94                         echo "PROJECT_NUMBER         = $PACKAGE_VERSION"
  95                         echo "OUTPUT_DIRECTORY       = $ABS_OUTDIR"
  96                         echo "STRIP_FROM_PATH        = $ABS_SRCDIR"
  97                         echo "INPUT                  = $ABS_SRCDIR"
  98                 ) | doxygen -q -
  99                 ;;
 100
 101         internal)
 102                 rm -rf "$ABS_OUTDIR/internal"
 103                 (
 104                         cat "$ABS_TOP_SRCDIR/doxygen/Doxyfile"
 105                         echo 'PROJECT_NAME           = "XZ Utils"'
 106                         echo "PROJECT_NUMBER         = $PACKAGE_VERSION"
 107                         echo "OUTPUT_DIRECTORY       = $ABS_OUTDIR"
 108                         echo "STRIP_FROM_PATH        = $ABS_TOP_SRCDIR"
 109                         echo "INPUT                  = $ABS_TOP_SRCDIR/src"
 110                         echo 'HTML_OUTPUT            = internal'
 111                         echo 'SEARCHENGINE           = YES'
 112                 ) | doxygen -q -
 113                 ;;
 114 esac