begriffs open source - cmsis/blob - CMSIS/Documentation/Doxygen/gen_doc.sh

   1 #!/usr/bin/env bash
   2 # Version: 3.0
   3 # Date: 2023-11-06
   4 # This bash script generates CMSIS documentation
   5 #
   6 # Pre-requisites:
   7 # - bash shell (for Windows: install git for Windows)
   8 # - doxygen 1.9.6
   9 # - mscgen 0.20
  10 # - linkchecker (can be skipped with -s)
  11
  12 set -o pipefail
  13
  14 # Set version of gen pack library
  15 # For available versions see https://github.com/Open-CMSIS-Pack/gen-pack/tags.
  16 # Use the tag name without the prefix "v", e.g., 0.7.0
  17 REQUIRED_GEN_PACK_LIB="0.11.1"
  18
  19 DIRNAME=$(dirname "$(readlink -f "$0")")
  20 GENDIR=../html
  21 REQ_DXY_VERSION="1.9.6"
  22 REQ_MSCGEN_VERSION="0.20"
  23
  24 RUN_LINKCHECKER=1
  25 COMPONENTS=()
  26
  27 function usage() {
  28   echo "Usage: $(basename "$0") [-h] [-s] [-c <comp>]"
  29   echo " -h,--help               Show usage"
  30   echo " -s,--no-linkcheck       Skip linkcheck"
  31   echo " -c,--component <comp>   Select component <comp> to generate documentation for. "
  32   echo "                         Can be given multiple times. Defaults to all components."
  33 }
  34
  35 while [[ $# -gt 0 ]]; do
  36   case $1 in
  37     '-h'|'help')
  38       usage
  39       exit 1
  40     ;;
  41     '-s'|'--no-linkcheck')
  42       RUN_LINKCHECKER=0
  43     ;;
  44     '-c'|'--component')
  45       shift
  46       COMPONENTS+=("$1")
  47     ;;
  48     *)
  49       echo "Invalid command line argument: $1" >&2
  50       usage
  51       exit 1
  52     ;;
  53   esac
  54   shift # past argument
  55 done
  56
  57 ############ DO NOT EDIT BELOW ###########
  58
  59 # Set GEN_PACK_LIB_PATH to use a specific gen-pack library root
  60 # ... instead of bootstrap based on REQUIRED_GEN_PACK_LIB
  61 if [[ -f "${GEN_PACK_LIB_PATH}/gen-pack" ]]; then
  62   . "${GEN_PACK_LIB_PATH}/gen-pack"
  63 else
  64   . <(curl -sL "https://raw.githubusercontent.com/Open-CMSIS-Pack/gen-pack/main/bootstrap")
  65 fi
  66
  67 find_git
  68 find_doxygen "${REQ_DXY_VERSION}"
  69 find_utility "mscgen" "-l | grep 'Mscgen version' | sed -r -e 's/Mscgen version ([^,]+),.*/\1/'" "${REQ_MSCGEN_VERSION}"
  70 [[ ${RUN_LINKCHECKER} != 0 ]] && find_linkchecker
  71
  72 if [ -z "${VERSION_FULL}" ]; then
  73   VERSION_FULL=$(git_describe "v")
  74 fi
  75
  76 pushd "${DIRNAME}" > /dev/null || exit 1
  77
  78 echo_log "Generating documentation ..."
  79
  80 function generate() {
  81   if [[ ! (${#COMPONENTS[@]} == 0 || ${COMPONENTS[*]} =~ $1) ]]; then
  82     return
  83   fi
  84
  85   pushd "$1" > /dev/null || exit 1
  86
  87   projectName=$(grep -E "PROJECT_NAME\s+=" "$1.dxy.in" | sed -r -e 's/[^"]*"([^"]+)".*/\1/')
  88   projectNumberFull="$2"
  89   if [ -z "${projectNumberFull}" ]; then
  90     projectNumberFull=$(grep -E "PROJECT_NUMBER\s+=" "$1.dxy.in" | sed -r -e 's/[^"]*"[^0-9]*(([0-9]+\.[0-9]+(\.[0-9]+)?(-.+)?)?)".*/\1/')
  91   fi
  92   if [ -z "${projectNumberFull}" ]; then
  93     projectNumberFull="$(git rev-parse --short HEAD)"
  94   fi
  95   projectNumber="${projectNumberFull%+*}"
  96   datetime=$(date -u +'%a %b %e %Y %H:%M:%S')
  97   year=$(date -u +'%Y')
  98
  99   sed -e "s/{projectNumber}/${projectNumber}/" "$1.dxy.in" > "$1.dxy"
 100
 101   mkdir -p "${DIRNAME}/${GENDIR}/$1/"
 102   # git_changelog -f html -p "v" > src/history.txt
 103
 104   echo_log "\"${UTILITY_DOXYGEN}\" \"$1.dxy\""
 105   "${UTILITY_DOXYGEN}" "$1.dxy"
 106
 107   mkdir -p "${DIRNAME}/${GENDIR}/$1/search/"
 108   cp -f "${DIRNAME}/style_template/search.css" "${DIRNAME}/${GENDIR}/$1/search/"
 109   cp -f "${DIRNAME}/style_template/navtree.js" "${DIRNAME}/${GENDIR}/$1/"
 110   cp -f "${DIRNAME}/style_template/resize.js" "${DIRNAME}/${GENDIR}/$1/"
 111
 112   sed -e "s/{datetime}/${datetime}/" "${DIRNAME}/style_template/footer.js.in" \
 113     | sed -e "s/{year}/${year}/" \
 114     | sed -e "s/{projectName}/${projectName}/" \
 115     | sed -e "s/{projectNumber}/${projectNumber}/" \
 116     | sed -e "s/{projectNumberFull}/${projectNumberFull}/" \
 117     > "${DIRNAME}/${GENDIR}/$1/footer.js"
 118
 119   popd > /dev/null || exit 1
 120 }
 121
 122 generate "General" "${VERSION_FULL}"
 123 generate "Core"
 124 generate "Core_A"
 125 generate "Driver"
 126 generate "RTOS2"
 127 generate "DSP"
 128 generate "NN"
 129 generate "View"
 130 generate "Compiler"
 131 generate "Toolbox"
 132 generate "Stream"
 133 generate "DAP"
 134 generate "Zone"
 135
 136 cp -f "${DIRNAME}/index.html" "${DIRNAME}/../html/"
 137
 138 [[ ${RUN_LINKCHECKER} != 0 ]] && check_links --timeout 120 "${DIRNAME}/../html/index.html" "${DIRNAME}"
 139
 140 popd > /dev/null || exit 1
 141
 142 exit 0