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     # to remove GPL licence section
  93     find "${WORKING_DIR}/tests/" -type f -exec sed -i '/\*\*\*/,$!d' {} \;
  94
  95     find ${WORKING_DIR}/ -type d -exec echo {} \; -exec touch {}/__init__.py \;
  96
  97     python3 gen_rst.py || die "Generate .rst files failed!"
  98
  99     # Generate the documentation:
 100     DATE=$(date -u '+%d-%b-%Y') || die "Get date failed!"
 101
 102     all_options=("-v")
 103     all_options+=("-c" "${WORKING_DIR}")
 104     all_options+=("-a")
 105     all_options+=("-b" "html")
 106     all_options+=("-E")
 107     all_options+=("-D" "version="${GERRIT_BRANCH:-master}"")
 108     all_options+=("${WORKING_DIR}" "${BUILD_DIR}/")
 109
 110     set +e
 111     sphinx-build "${all_options[@]}"
 112     DOCS_EXIT_STATUS="$?"
 113     set -e
 114 }
 115
 116 function generate_report () {
 117
 118     # Generate report content.
 119     #
 120     # Variable read:
 121     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 122     # - ${GERRIT_BRANCH} - Gerrit branch used for release tagging.
 123     # Variables set:
 124     # - DOCS_EXIT_STATUS - Exit status of report generation.
 125     # Functions called:
 126     # - die - Print to stderr and exit.
 127
 128     set -exuo pipefail
 129
 130     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 131
 132     # Set default values in config array.
 133     typeset -A CFG
 134     typeset -A DIR
 135
 136     DIR[WORKING]="_tmp"
 137
 138     # Create working directories.
 139     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 140
 141     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 142
 143     all_options=("pal.py")
 144     all_options+=("--specification" "specifications/report")
 145     all_options+=("--release" "${GERRIT_BRANCH:-master}")
 146     all_options+=("--week" $(date "+%V"))
 147     all_options+=("--logging" "INFO")
 148     all_options+=("--force")
 149
 150     set +e
 151     python "${all_options[@]}"
 152     DOCS_EXIT_STATUS="$?"
 153     set -e
 154
 155 }
 156
 157 function generate_report_local () {
 158
 159     # Generate report from local content.
 160     #
 161     # Variable read:
 162     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 163     # - ${CSIT_REPORT_FILENAME} - Source filename.
 164     # - ${CSIT_REPORT_DIRECTORYNAME} - Source directory.
 165     # - ${CSIT_REPORT_INSTALL_DEPENDENCIES} - Whether to install dependencies.
 166     # - ${CSIT_REPORT_INSTALL_LATEX} - Whether to install latex.
 167     # Variables set:
 168     # - DOCS_EXIT_STATUS - Exit status of report generation.
 169     # Functions called:
 170     # - die - Print to stderr and exit.
 171
 172     set -exuo pipefail
 173
 174     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 175
 176     filename="${CSIT_REPORT_FILENAME-}"
 177     directoryname="${CSIT_REPORT_DIRECTORYNAME-}"
 178     install_dependencies="${CSIT_REPORT_INSTALL_DEPENDENCIES:-1}"
 179     install_latex="${CSIT_REPORT_INSTALL_LATEX:-0}"
 180
 181     # Set default values in config array.
 182     typeset -A CFG
 183     typeset -A DIR
 184
 185     DIR[WORKING]="_tmp"
 186
 187     # Install system dependencies.
 188     if [[ ${install_dependencies} -eq 1 ]] ;
 189     then
 190         sudo apt -y update || die "APT update failed!"
 191         sudo apt -y install libxml2 libxml2-dev libxslt-dev \
 192             build-essential zlib1g-dev unzip || die "APT install failed!"
 193     fi
 194
 195     if [[ ${install_latex} -eq 1 ]] ;
 196     then
 197         sudo apt -y update || die "APT update failed!"
 198         sudo apt -y install xvfb texlive-latex-recommended \
 199             texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra \
 200             latexmk wkhtmltopdf inkscape || die "APT install failed!"
 201         target="/usr/share/texlive/texmf-dist/web2c/texmf.cnf"
 202         sudo sed -i.bak 's/^\(main_memory\s=\s\).*/\110000000/' "${target}" || {
 203             die "Patching latex failed!"
 204         }
 205     fi
 206
 207     # Create working directories.
 208     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 209
 210     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 211
 212     all_options=("pal.py")
 213     all_options+=("--specification" "specifications/report_local")
 214     all_options+=("--release" "${RELEASE:-master}")
 215     all_options+=("--week" "${WEEK:-1}")
 216     all_options+=("--logging" "INFO")
 217     all_options+=("--force")
 218     if [[ ${filename} != "" ]]; then
 219         all_options+=("--input-file" "${filename}")
 220     fi
 221     if [[ ${directoryname} != "" ]]; then
 222         all_options+=("--input-directory" "${directoryname}")
 223     fi
 224
 225     set +e
 226     python "${all_options[@]}"
 227     DOCS_EXIT_STATUS="$?"
 228     set -e
 229
 230 }
 231
 232 function generate_trending () {
 233
 234     # Generate trending content.
 235     #
 236     # Variable read:
 237     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 238     # Variables set:
 239     # - DOCS_EXIT_STATUS - Exit status of trending generation.
 240     # Functions called:
 241     # - die - Print to stderr and exit.
 242
 243     set -exuo pipefail
 244
 245     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 246
 247     # Set default values in config array.
 248     typeset -A DIR
 249
 250     DIR[WORKING]="_tmp"
 251
 252     # Create working directories.
 253     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 254
 255     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 256
 257     all_options=("pal.py")
 258     all_options+=("--specification" "specifications/trending")
 259     all_options+=("--logging" "INFO")
 260     all_options+=("--force")
 261
 262     set +e
 263     python "${all_options[@]}"
 264     DOCS_EXIT_STATUS="$?"
 265     set -e
 266
 267 }