Home | History | Annotate | Line # | Download | only in 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
    115