doc: Update functions documentation

cdalvaro · Nov 5, 2021 · 452c1f5 · 452c1f5
1 parent 8d3f031
commit 452c1f5
Show file tree

Hide file tree

Showing 3 changed files with 76 additions and 50 deletions.
diff --git a/assets/build/functions.sh b/assets/build/functions.sh
@@ -2,36 +2,13 @@
 
 set -e
 
-#---  FUNCTION  -------------------------------------------------------------------------------------------------------
-#          NAME:  __detect_color_support
-#   DESCRIPTION:  Try to detect color support.
-#----------------------------------------------------------------------------------------------------------------------
-_COLORS=${BS_COLORS:-$(tput colors 2>/dev/null || echo 0)}
-__detect_color_support() {
-    # shellcheck disable=SC2181
-    if [ $? -eq 0 ] && [ "$_COLORS" -gt 2 ]; then
-        RC='\033[1;31m'
-        GC='\033[1;32m'
-        BC='\033[1;34m'
-        YC='\033[1;33m'
-        EC='\033[0m'
-    else
-        RC=""
-        GC=""
-        BC=""
-        YC=""
-        EC=""
-    fi
-}
-__detect_color_support
-
 #---  FUNCTION  -------------------------------------------------------------------------------------------------------
 #          NAME:  log_debug
 #   DESCRIPTION:  Echo debug information to stdout.
 #----------------------------------------------------------------------------------------------------------------------
 function log_debug() {
   if [[ "${DEBUG}" == 'true' || "${ECHO_DEBUG}" == 'true' ]]; then
-    echo -e "${BC} *  DEBUG${EC}: $*"
+    echo " *  DEBUG: $*"
   fi
 }
 
@@ -40,15 +17,15 @@ function log_debug() {
 #   DESCRIPTION:  Echo information to stdout.
 #----------------------------------------------------------------------------------------------------------------------
 function log_info() {
-  echo -e "${GC} *  INFO${EC}: $*"
+  echo " *  INFO: $*"
 }
 
 #---  FUNCTION  -------------------------------------------------------------------------------------------------------
 #          NAME:  log_warn
 #   DESCRIPTION:  Echo warning information to stdout.
 #----------------------------------------------------------------------------------------------------------------------
 function log_warn() {
-  echo -e "${YC} *  WARN${EC}: $*"
+  echo " *  WARN: $*"
 }
 
 #---  FUNCTION  -------------------------------------------------------------------------------------------------------
@@ -57,12 +34,12 @@ function log_warn() {
 #----------------------------------------------------------------------------------------------------------------------
 function log_error()
 {
-  (>&2 echo -e "${RC} *  ERROR${EC}: $*")
+  (>&2 echo " *  ERROR: $*")
 }
 
 #---  FUNCTION  -------------------------------------------------------------------------------------------------------
 #          NAME:  exec_as_salt
-#   DESCRIPTION:  Execute the pass command as the `salt` user.
+#   DESCRIPTION:  Execute the pass command as the `SALT_USER` user.
 #----------------------------------------------------------------------------------------------------------------------
 function exec_as_salt()
 {
@@ -100,9 +77,13 @@ function is_arm()
   is_arm32 || is_arm64
 }
 
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  install_pkgs
+#   DESCRIPTION:  Install packages using apt-get install.
+#----------------------------------------------------------------------------------------------------------------------
 function install_pkgs()
 {
-  apt-get install --no-install-recommends -y $@
+  apt-get install --no-install-recommends --yes $@
 }
 
 #---  FUNCTION  -------------------------------------------------------------------------------------------------------
@@ -213,7 +194,10 @@ function install_libssh2()
   rm -rf "${WORK_DIR}"
 }
 
-# Install libgit2 library
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  install_libgit2
+#   DESCRIPTION:  Install libgit2 library.
+#----------------------------------------------------------------------------------------------------------------------
 function install_libgit2()
 {
   local LIBGIT2_VERSION=1.3.0

diff --git a/assets/build/install.sh b/assets/build/install.sh
@@ -19,8 +19,7 @@ BUILD_DEPENDENCIES=(
 )
 
 apt-get update
-apt-get install --no-install-recommends -y \
-  "${REQUIRED_PACKAGES[@]}" "${BUILD_DEPENDENCIES[@]}"
+install_pkgs "${REQUIRED_PACKAGES[@]}" "${BUILD_DEPENDENCIES[@]}"
 
 # Create salt user
 log_info "Creating ${SALT_USER} user ..."
@@ -33,7 +32,7 @@ EOF
 
 # Install python3 packages
 log_info "Installing python3 packages ..."
-apt-get install --yes --quiet --no-install-recommends \
+install_pkgs --quiet \
   python3-mako python3-pycryptodome python3-cherrypy3 \
   python3-git python3-requests python3-redis python3-gnupg \
   python3-mysqldb python3-dateutil python3-libnacl python3-openssl

diff --git a/assets/runtime/functions.sh b/assets/runtime/functions.sh
@@ -9,7 +9,10 @@ source "${ENV_DEFAULTS_FILE}"
 # cdalvaro managed block string
 SELF_MANAGED_BLOCK_STRING="## cdalvaro managed block"
 
-# Execute a command as SALT_USER
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  exec_as_salt
+#   DESCRIPTION:  Execute the pass command as the `SALT_USER` user.
+#----------------------------------------------------------------------------------------------------------------------
 function exec_as_salt()
 {
   if [[ $(whoami) == "${SALT_USER}" ]]; then
@@ -19,13 +22,19 @@ function exec_as_salt()
   fi
 }
 
-# Log error
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  log_error
+#   DESCRIPTION:  Echo errors to stderr.
+#----------------------------------------------------------------------------------------------------------------------
 function log_error()
 {
-  (>&2 echo "ERROR: $*")
+  (>&2 echo " *  ERROR: $*")
 }
 
-# Map salt user with host user
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  map_uidgid
+#   DESCRIPTION:  Map salt user with host user.
+#----------------------------------------------------------------------------------------------------------------------
 function map_uidgid()
 {
   USERMAP_ORIG_UID=$(id -u "${SALT_USER}")
@@ -48,9 +57,13 @@ function map_uidgid()
   fi
 }
 
-# This function replaces placeholders with values
-# $1: file with placeholders to replace
-# $x: placeholders to replace
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  update_template
+#   DESCRIPTION:  Replace placeholders with values.
+#     ARGUMENTS:
+#           - 1: Template file with placeholders to replace
+#           - @: Placeholder values
+#----------------------------------------------------------------------------------------------------------------------
 function update_template()
 {
   local FILE=${1?missing argument}
@@ -77,7 +90,10 @@ function update_template()
   rm -f "${tmp_file}"
 }
 
-# This function configures containers timezone
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  configure_timezone
+#   DESCRIPTION:  Configure containers timezone.
+#----------------------------------------------------------------------------------------------------------------------
 function configure_timezone()
 {
   echo "Configuring container timezone ..."
@@ -97,7 +113,10 @@ function configure_timezone()
   fi
 }
 
-# This function generates a master_sign key pair and its signature
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  gen_signed_keys
+#   DESCRIPTION:  Generate a master_sign key pair and its signature.
+#----------------------------------------------------------------------------------------------------------------------
 function gen_signed_keys()
 {
   local key_name=${1:-master}
@@ -111,7 +130,10 @@ function gen_signed_keys()
   echo -n "${GENERATED_KEYS_DIR}"
 }
 
-# This function repairs keys permissions and creates keys if neaded
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  setup_salt_keys
+#   DESCRIPTION:  Repair keys permissions and creates keys if neaded.
+#----------------------------------------------------------------------------------------------------------------------
 function setup_salt_keys()
 {
   echo "Setting up salt keys ..."
@@ -138,7 +160,10 @@ function setup_salt_keys()
   find "${SALT_HOME}" -path "${SALT_KEYS_DIR}/*" -print0 | xargs -0 chown -h "${SALT_USER}":
 }
 
-# This function configures ssh keys
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  setup_ssh_keys
+#   DESCRIPTION:  Configure ssh keys.
+#----------------------------------------------------------------------------------------------------------------------
 function setup_ssh_keys()
 {
   echo "Configuring ssh ..."
@@ -156,7 +181,10 @@ function setup_ssh_keys()
   fi
 }
 
-# This function cofigures master service
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  configure_salt_master
+#   DESCRIPTION:  Configure master service.
+#----------------------------------------------------------------------------------------------------------------------
 function configure_salt_master()
 {
   echo "Configuring salt-master service ..."
@@ -183,7 +211,10 @@ function configure_salt_master()
     SALT_MASTER_USE_PUBKEY_SIGNATURE
 }
 
-# This function configures salt-api if service is set to be enabled
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  configure_salt_api
+#   DESCRIPTION:  Configure salt-api if service is set to be enabled.
+#----------------------------------------------------------------------------------------------------------------------
 function configure_salt_api()
 {
   [[ ${SALT_API_SERVICE_ENABLED} == true ]] || return 0
@@ -246,7 +277,10 @@ EOF
 
 }
 
-# This function configures salt-formulas
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  configure_salt_formulas
+#   DESCRIPTION:  Configure salt-formulas.
+#----------------------------------------------------------------------------------------------------------------------
 function configure_salt_formulas()
 {
   echo "Configuring 3rd-party salt-formulas ..."
@@ -266,7 +300,10 @@ function configure_salt_formulas()
   rm "${tmp_file}"
 }
 
-# Initializes main directories
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  initialize_datadir
+#   DESCRIPTION:  Initialize main directories.
+#----------------------------------------------------------------------------------------------------------------------
 function initialize_datadir()
 {
   echo "Configuring directories ..."
@@ -328,7 +365,10 @@ function initialize_datadir()
   chown -R "${SALT_USER}": "${SALT_LOGS_DIR}/salt"
 }
 
-# Configures logrotate
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  configure_logrotate
+#   DESCRIPTION:  Configure logrotate.
+#----------------------------------------------------------------------------------------------------------------------
 function configure_logrotate()
 {
   echo "Configuring logrotate ..."
@@ -391,7 +431,10 @@ EOF
 
 }
 
-# Initializes the system
+#---  FUNCTION  -------------------------------------------------------------------------------------------------------
+#          NAME:  initialize_system
+#   DESCRIPTION:  Initialize the system.
+#----------------------------------------------------------------------------------------------------------------------
 function initialize_system()
 {
   map_uidgid