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     WORKING_DIR="tmp"
  51     BUILD_DIR="_build"
  52
  53     # Create working directories
  54     mkdir "${BUILD_DIR}"
  55     mkdir --parents "${WORKING_DIR}"/resources/libraries/python/
  56     mkdir --parents "${WORKING_DIR}"/resources/libraries/robot/
  57     mkdir --parents "${WORKING_DIR}"/tests/
  58
  59     # Copy the Sphinx source files:
  60     cp -r src/* ${WORKING_DIR}/
  61
  62     # Copy the source files to be processed:
  63     from_dir="../../../resources/libraries/python/"
  64     to_dir="${WORKING_DIR}/resources/libraries/python/"
  65     command="rsync -a --include '*/'"
  66     ${command} --include '*.py' --exclude '*' "${from_dir}" "${to_dir}"
  67     cp ../../../resources/__init__.py ${WORKING_DIR}/resources/
  68     cp ../../../resources/libraries/__init__.py ${WORKING_DIR}/resources/libraries/
  69     from_dir="../../../resources/libraries/robot/"
  70     to_dir="${WORKING_DIR}/resources/libraries/robot/"
  71     ${command} --include '*.robot' --exclude '*' "${from_dir}" "${to_dir}"
  72     from_dir="../../../tests/"
  73     to_dir="${WORKING_DIR}/tests/"
  74     ${command} --include '*.robot' --exclude '*' "${from_dir}" "${to_dir}"
  75
  76     python3 gen_rst.py
  77     # Remove all rst files from ./${WORKING_DIR}/env directory - we do not need
  78     # them
  79     find ./${WORKING_DIR}/env -type f -name '*.rst' | xargs rm -f
  80
  81     # Generate the documentation:
  82     DATE=$(date -u '+%d-%b-%Y')
  83
  84     all_options=("-v")
  85     all_options+=("-c" "${WORKING_DIR}")
  86     all_options+=("-a")
  87     all_options+=("-b" "html")
  88     all_options+=("-E")
  89     all_options+=("-D" "release=$1")
  90     all_options+=("-D" "version='$1 documentation - $DATE'")
  91     all_options+=("${WORKING_DIR}" "${BUILD_DIR}/")
  92
  93     set +e
  94     sphinx-build "${all_options[@]}"
  95     DOCS_EXIT_STATUS="$?"
  96     set -e
  97
  98     find . -type d -name 'env' | xargs rm -rf
  99
 100 }
 101
 102 function generate_report () {
 103
 104     # Generate report content.
 105     #
 106     # Variable read:
 107     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 108     # - ${GERRIT_BRANCH} - Gerrit branch used for release tagging.
 109     # Variables set:
 110     # - DOCS_EXIT_STATUS - Exit status of report generation.
 111     # Functions called:
 112     # - die - Print to stderr and exit.
 113
 114     set -exuo pipefail
 115
 116     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 117
 118     # Set default values in config array.
 119     typeset -A CFG
 120     typeset -A DIR
 121
 122     DIR[WORKING]="_tmp"
 123
 124     # Create working directories.
 125     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 126
 127     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 128
 129     all_options=("pal.py")
 130     all_options+=("--specification" "specifications/report")
 131     all_options+=("--release" "${GERRIT_BRANCH:-master}")
 132     all_options+=("--week" $(date "+%V"))
 133     all_options+=("--logging" "INFO")
 134     all_options+=("--force")
 135
 136     set +e
 137     python "${all_options[@]}"
 138     DOCS_EXIT_STATUS="$?"
 139     set -e
 140
 141 }
 142
 143 function generate_report_local () {
 144
 145     # Generate report from local content.
 146     #
 147     # Variable read:
 148     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 149     # - ${CSIT_REPORT_FILENAME} - Source filename.
 150     # - ${CSIT_REPORT_DIRECTORYNAME} - Source directory.
 151     # - ${CSIT_REPORT_INSTALL_DEPENDENCIES} - Whether to install dependencies.
 152     # - ${CSIT_REPORT_INSTALL_LATEX} - Whether to install latex.
 153     # Variables set:
 154     # - DOCS_EXIT_STATUS - Exit status of report generation.
 155     # Functions called:
 156     # - die - Print to stderr and exit.
 157
 158     set -exuo pipefail
 159
 160     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 161
 162     filename="${CSIT_REPORT_FILENAME-}"
 163     directoryname="${CSIT_REPORT_DIRECTORYNAME-}"
 164     install_dependencies="${CSIT_REPORT_INSTALL_DEPENDENCIES:-1}"
 165     install_latex="${CSIT_REPORT_INSTALL_LATEX:-0}"
 166
 167     # Set default values in config array.
 168     typeset -A CFG
 169     typeset -A DIR
 170
 171     DIR[WORKING]="_tmp"
 172
 173     # Install system dependencies.
 174     if [[ ${install_dependencies} -eq 1 ]] ;
 175     then
 176         sudo apt -y update || die "APT update failed!"
 177         sudo apt -y install libxml2 libxml2-dev libxslt-dev \
 178             build-essential zlib1g-dev unzip || die "APT install failed!"
 179     fi
 180
 181     if [[ ${install_latex} -eq 1 ]] ;
 182     then
 183         sudo apt -y update || die "APT update failed!"
 184         sudo apt -y install xvfb texlive-latex-recommended \
 185             texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra \
 186             latexmk wkhtmltopdf inkscape || die "APT install failed!"
 187         target="/usr/share/texlive/texmf-dist/web2c/texmf.cnf"
 188         sudo sed -i.bak 's/^\(main_memory\s=\s\).*/\110000000/' "${target}" || {
 189             die "Patching latex failed!"
 190         }
 191     fi
 192
 193     # Create working directories.
 194     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 195
 196     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 197
 198     all_options=("pal.py")
 199     all_options+=("--specification" "specifications/report_local")
 200     all_options+=("--release" "${RELEASE:-master}")
 201     all_options+=("--week" "${WEEK:-1}")
 202     all_options+=("--logging" "INFO")
 203     all_options+=("--force")
 204     if [[ ${filename} != "" ]]; then
 205         all_options+=("--input-file" "${filename}")
 206     fi
 207     if [[ ${directoryname} != "" ]]; then
 208         all_options+=("--input-directory" "${directoryname}")
 209     fi
 210
 211     set +e
 212     python "${all_options[@]}"
 213     DOCS_EXIT_STATUS="$?"
 214     set -e
 215
 216 }
 217
 218 function generate_trending () {
 219
 220     # Generate trending content.
 221     #
 222     # Variable read:
 223     # - ${TOOLS_DIR} - Path to existing resources subdirectory "tools".
 224     # Variables set:
 225     # - DOCS_EXIT_STATUS - Exit status of trending generation.
 226     # Functions called:
 227     # - die - Print to stderr and exit.
 228
 229     set -exuo pipefail
 230
 231     pushd "${TOOLS_DIR}"/presentation || die "Pushd failed!"
 232
 233     # Set default values in config array.
 234     typeset -A DIR
 235
 236     DIR[WORKING]="_tmp"
 237
 238     # Create working directories.
 239     mkdir "${DIR[WORKING]}" || die "Mkdir failed!"
 240
 241     export PYTHONPATH=`pwd`:`pwd`/../../../ || die "Export failed!"
 242
 243     all_options=("pal.py")
 244     all_options+=("--specification" "specifications/trending")
 245     all_options+=("--logging" "INFO")
 246     all_options+=("--force")
 247
 248     set +e
 249     python "${all_options[@]}"
 250     DOCS_EXIT_STATUS="$?"
 251     set -e
 252
 253 }