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