resources/libraries/bash/function/docs.sh

   1 #!/usr/bin/env bash
   2
   3 # Copyright (c) 2021 Cisco and/or its affiliates.
   4 # Licensed under the Apache License, Version 2.0 (the "License");
   5 # you may not use this file except in compliance with the License.
   6 # You may obtain a copy of the License at:
   7 #
   8 #     http://www.apache.org/licenses/LICENSE-2.0
   9 #
  10 # Unless required by applicable law or agreed to in writing, software
  11 # distributed under the License is distributed on an "AS IS" BASIS,
  12 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 # See the License for the specific language governing permissions and
  14 # limitations under the License.
  15
  16 set -exuo pipefail
  17
  18
  19 function die_on_docs_error () {
  20
  21     # Source this fragment if you want to abort on any failure.
  22     #
  23     # Variables read:
  24     # - DOCS_EXIT_STATUS - Set by a generation function.
  25     # Functions called:
  26     # - die - Print to stderr and exit.
  27
  28     set -exuo pipefail
  29
  30     if [[ "${DOCS_EXIT_STATUS}" != "0" ]]; then
  31         die "Failed to generate docs!" "${DOCS_EXIT_STATUS}"
  32     fi
  33 }
  34
  35 function generate_docs () {
  36
  37     # Generate docs content.
  38     #
  39     # Variable read:
  40     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
  41     # Variables set:
  42     # - DOCS_EXIT_STATUS - Exit status of docs generation.
  43     # Functions called:
  44     # - die - Print to stderr and exit.
  45
  46     set -exuo pipefail
  47
  48     pushd "${TOOLS_DIR}"/doc_gen || die "Pushd failed!"
  49
  50     BUILD_DIR="_build"
  51
  52     # Remove the old build:
  53     rm -rf ${BUILD_DIR} || true
  54     rm -rf /tmp/tmp-csit* || true
  55
  56     export WORKING_DIR=$(mktemp -d /tmp/tmp-csitXXX) || die "export failed"
  57
  58     # Create working directories
  59     mkdir -p "${BUILD_DIR}" || die "Mkdir failed!"
  60     mkdir -p "${WORKING_DIR}"/resources/libraries/python/ || die "Mkdir failed!"
  61     mkdir -p "${WORKING_DIR}"/resources/libraries/robot/ || die "Mkdir failed!"
  62     mkdir -p "${WORKING_DIR}"/tests/ || die "Mkdir failed!"
  63
  64     # Copy the Sphinx source files:
  65     cp -r src/* ${WORKING_DIR}/ || die "Copy the Sphinx source files failed!"
  66
  67     # Copy the source files to be processed:
  68     from_dir="${RESOURCES_DIR}/libraries/python/"
  69     to_dir="${WORKING_DIR}/resources/libraries/python/"
  70     dirs="${from_dir} ${to_dir}"
  71     rsync -ar --include='*/' --include='*.py' --exclude='*' ${dirs} || {
  72         die "rSync failed!"
  73     }
  74
  75     from_dir="${RESOURCES_DIR}/libraries/robot/"
  76     to_dir="${WORKING_DIR}/resources/libraries/robot/"
  77     dirs="${from_dir} ${to_dir}"
  78     rsync -ar --include='*/' --include '*.robot' --exclude '*' ${dirs} || {
  79         die "rSync failed!"
  80     }
  81     touch ${to_dir}/index.robot || {
  82         die "Touch index.robot file failed!"
  83     }
  84
  85     from_dir="${CSIT_DIR}/tests/"
  86     to_dir="${WORKING_DIR}/tests/"
  87     dirs="${from_dir} ${to_dir}"
  88     rsync -ar --include='*/' --include '*.robot' --exclude '*' ${dirs} || {
  89         die "rSync failed!"
  90     }
  91
  92     find ${WORKING_DIR}/ -type d -exec echo {} \; -exec touch {}/__init__.py \;
  93
  94     python3 gen_rst.py || die "Generate .rst files failed!"
  95
  96     # Generate the documentation:
  97     DATE=$(date -u '+%d-%b-%Y') || die "Get date failed!"
  98
  99     all_options=("-v")
 100     all_options+=("-c" "${WORKING_DIR}")
 101     all_options+=("-a")
 102     all_options+=("-b" "html")
 103     all_options+=("-E")
 104     all_options+=("-D" "version="${GERRIT_BRANCH:-master}"")
 105     all_options+=("${WORKING_DIR}" "${BUILD_DIR}/")
 106
 107     set +e
 108     sphinx-build "${all_options[@]}"
 109     DOCS_EXIT_STATUS="$?"
 110     set -e
 111 }
 112
 113 function generate_report () {
 114
 115     # Generate report content.
 116     #
 117     # Variable read:
 118     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 119     # - ${GERRIT_BRANCH} - Gerrit branch used for release tagging.
 120     # Variables set:
 121     # - DOCS_EXIT_STATUS - Exit status of report generation.
 122     # Functions called:
 123     # - die - Print to stderr and exit.
 124
 125     set -exuo pipefail
 126
 127     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 128
 129     # Set default values in config array.
 130     typeset -A CFG
 131     typeset -A DIR
 132
 133     DIR[WORKING]="_tmp"
 134
 135     # Create working directories.
 136     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 137
 138     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 139
 140     all_options=("pal.py")
 141     all_options+=("--specification" "specifications/report")
 142     all_options+=("--release" "${GERRIT_BRANCH:-master}")
 143     all_options+=("--week" $(date "+%V"))
 144     all_options+=("--logging" "INFO")
 145     all_options+=("--force")
 146
 147     set +e
 148     python "${all_options[@]}"
 149     DOCS_EXIT_STATUS="$?"
 150     set -e
 151
 152 }
 153
 154 function generate_report_local () {
 155
 156     # Generate report from local content.
 157     #
 158     # Variable read:
 159     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 160     # - ${CSIT_REPORT_FILENAME} - Source filename.
 161     # - ${CSIT_REPORT_DIRECTORYNAME} - Source directory.
 162     # - ${CSIT_REPORT_INSTALL_DEPENDENCIES} - Whether to install dependencies.
 163     # - ${CSIT_REPORT_INSTALL_LATEX} - Whether to install latex.
 164     # Variables set:
 165     # - DOCS_EXIT_STATUS - Exit status of report generation.
 166     # Functions called:
 167     # - die - Print to stderr and exit.
 168
 169     set -exuo pipefail
 170
 171     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 172
 173     filename="${CSIT_REPORT_FILENAME-}"
 174     directoryname="${CSIT_REPORT_DIRECTORYNAME-}"
 175     install_dependencies="${CSIT_REPORT_INSTALL_DEPENDENCIES:-1}"
 176     install_latex="${CSIT_REPORT_INSTALL_LATEX:-0}"
 177
 178     # Set default values in config array.
 179     typeset -A CFG
 180     typeset -A DIR
 181
 182     DIR[WORKING]="_tmp"
 183
 184     # Install system dependencies.
 185     if [[ ${install_dependencies} -eq 1 ]] ;
 186     then
 187         sudo apt -y update || die "APT update failed!"
 188         sudo apt -y install libxml2 libxml2-dev libxslt-dev \
 189             build-essential zlib1g-dev unzip || die "APT install failed!"
 190     fi
 191
 192     if [[ ${install_latex} -eq 1 ]] ;
 193     then
 194         sudo apt -y update || die "APT update failed!"
 195         sudo apt -y install xvfb texlive-latex-recommended \
 196             texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra \
 197             latexmk wkhtmltopdf inkscape || die "APT install failed!"
 198         target="/usr/share/texlive/texmf-dist/web2c/texmf.cnf"
 199         sudo sed -i.bak 's/^\(main_memory\s=\s\).*/\110000000/' "${target}" || {
 200             die "Patching latex failed!"
 201         }
 202     fi
 203
 204     # Create working directories.
 205     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 206
 207     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 208
 209     all_options=("pal.py")
 210     all_options+=("--specification" "specifications/report_local")
 211     all_options+=("--release" "${RELEASE:-master}")
 212     all_options+=("--week" "${WEEK:-1}")
 213     all_options+=("--logging" "INFO")
 214     all_options+=("--force")
 215     if [[ ${filename} != "" ]]; then
 216         all_options+=("--input-file" "${filename}")
 217     fi
 218     if [[ ${directoryname} != "" ]]; then
 219         all_options+=("--input-directory" "${directoryname}")
 220     fi
 221
 222     set +e
 223     python "${all_options[@]}"
 224     DOCS_EXIT_STATUS="$?"
 225     set -e
 226
 227 }
 228
 229 function generate_trending () {
 230
 231     # Generate trending content.
 232     #
 233     # Variable read:
 234     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 235     # Variables set:
 236     # - DOCS_EXIT_STATUS - Exit status of trending generation.
 237     # Functions called:
 238     # - die - Print to stderr and exit.
 239
 240     set -exuo pipefail
 241
 242     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 243
 244     # Set default values in config array.
 245     typeset -A DIR
 246
 247     DIR[WORKING]="_tmp"
 248
 249     # Create working directories.
 250     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 251
 252     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 253
 254     all_options=("pal.py")
 255     all_options+=("--specification" "specifications/trending")
 256     all_options+=("--logging" "INFO")
 257     all_options+=("--force")
 258
 259     set +e
 260     python "${all_options[@]}"
 261     DOCS_EXIT_STATUS="$?"
 262     set -e
 263
 264 }