Document environment variables

Author: JohT

COMMANDS.md

@@ -115,7 +115,7 @@ Change into the [cypher](./cypher/) directory e.g. with `cd cypher` and then exe
 Change into the [scripts](./scripts/) directory e.g. with `cd scripts` and then execute the script [generateScriptReference.sh](./scripts/generateScriptReference.sh) with the following command:
 
 ```script
-./../scripts/generateScriptReference.sh
+./generateScriptReference.sh
 ```
 
 ### Update Markdown Reference
@@ -125,11 +125,18 @@ Change into the [results](./results/) directory e.g. with `cd results` and then
 👉**Note:** This script is automatically triggered at the end of [copyReportsIntoResults.sh](./scripts/copyReportsIntoResults.sh)
 which is included in the pipeline [code-reports.yml](.github/workflows/code-reports.yml) and doesn't need to be executed manually normally.
 
-
 ```script
 ./../scripts/generateScriptReference.sh
 ```
 
+### Update Environment Variable Reference
+
+Change into the [scripts](./scripts/) directory e.g. with `cd scripts` and then execute the script [generateEnvironmentVariablesReference.sh](./scripts/generateEnvironmentVariablesReference.sh) with the following command:
+
+```script
+./generateEnvironmentVariablesReference.sh
+```
+
 ## Manual Setup
 
 The manual setup is only documented for completeness. It isn't needed since the analysis also covers download, installation and configuration of all needed tools.

README.md

@@ -94,6 +94,10 @@ The [Code Reports Pipeline](./.github/workflows/code-reports.yml) utilizes [GitH
 
 [COMMANDS.md](./COMMANDS.md) contains further details on commands and how to do a manual setup.
 
+## 🛠 Environment Variable Reference
+
+[ENVIRONMENT_VARIABLES.md](./scripts/ENVIRONMENT_VARIABLES.md) contains all environment variables that are used in the scripts including default values and description. It can updated as described in [Update Environment Variable Reference](./COMMANDS.md#update-environment-variable-reference) of the [Commands Reference](./COMMANDS.md).
+
 ## 🤔 Questions & Answers
 
 - How can i run an analysis locally?  

scripts/appendEnvironmentVariables.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+
+# Extracts the environment variable declarations including default values from a script file and appends it to a markdown file as table columns.
+
+# Markdown file name
+markdownFile="ENVIRONMENT_VARIABLES.md"
+
+# Get the file to search for environment variables from the first (and only) command line option
+filePath="$1"
+
+# Check if the given file exists
+if [ -z "${filePath}" ] ; then
+    echo "findEnvironmentVariables: Please provide a file name."
+    exit 0
+fi
+
+# Check if the given file exists
+if [ ! -f "./${filePath}" ] ; then
+    echo "findEnvironmentVariables: File ${filePath} doesn't exist."
+    exit 0
+fi
+
+# Create the markdown file if it doesn't exist with the header of the table
+if [ ! -f "./${markdownFile}" ] ; then
+    echo "findEnvironmentVariables: Creating ${markdownFile}..."
+    { 
+        echo "# Environment Variables Reference" 
+        echo ""
+        echo "This document serves as a reference for all environment variables that are supported by the script files."
+        echo "It provides a table listing each environment variable, its default value and its corresponding description provided as a inline comment."
+        echo ""
+        echo "| Environment Variable Name           | Default                             | Description                                            |"
+        echo "| ----------------------------------- | ----------------------------------- | ------------------------------------------------------ |"
+    } > ${markdownFile}
+fi
+
+# Regular expression that extracts the environment variable name (1st group), its default value (2nd group) and its description (3rd group)
+regular_expression='^[[:space:]]*([A-Za-z_][A-Za-z0-9_]*)=\${[A-Za-z_][A-Za-z0-9_]*:-"([^"]*)"}[[:space:]]*#*[[:space:]]*(.*)'
+
+environmentVariables=$(\
+    # Use grep to find lines with the pattern you specified
+    grep -E "${regular_expression}" "$filePath" |
+    # Use sed to extract the variable name and default value
+    sed -E "s/${regular_expression}/\1;\2;\3/" |
+    # Use awk to format the output as requested
+    awk -F ';' '{ printf "%-37s | %-35s | %s |\n", $1, $2, $3 }'\
+)
+
+# Iterate over each environment variable line by line
+while IFS= read -r environmentVariable; do
+    # Append the previously found environment variable to the markdown file if it isn't contained there yet.
+    if ! grep -q "${environmentVariable}" "$markdownFile"; then
+        echo "${environmentVariable}" >> ${markdownFile}
+    fi
+done <<< "$environmentVariables"

scripts/generateEnvironmentVariablesReference.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+
+# Runs "appendEnvironmentVariable.sh" for every script file in the current directory and its sub directories.
+
+# Requires appendEnvironmentVariable.sh
+
+## Get this "scripts" directory if not already set
+# Even if $BASH_SOURCE is made for Bourne-like shells it is also supported by others and therefore here the preferred solution. 
+# CDPATH reduces the scope of the cd command to potentially prevent unintended directory changes.
+# This way non-standard tools like readlink aren't needed.
+SCRIPTS_DIR=${SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )}
+echo "generateEnvironmentVariablesReference: SCRIPTS_DIR=${SCRIPTS_DIR}"
+
+# Loop through all script files in the current directory
+find . -type f -name "*.sh" | sort | while read -r scriptFile; do
+  echo "generateEnvironmentVariablesReference: Searching for environment variables in ${scriptFile}"
+  source "${SCRIPTS_DIR}/appendEnvironmentVariables.sh" "${scriptFile}"
+done