Include domains in documentation generation

Author: JohT

.github/workflows/internal-environment-variables-reference-documentation.yml

@@ -28,9 +28,8 @@ jobs:
         token: ${{ secrets.WORKFLOW_GIT_ACCESS_TOKEN }}
 
     - name: Generate environment variables reference document
-      working-directory: scripts
       run: |
-        ./documentation/generateEnvironmentVariableReference.sh
+        ./scripts/documentation/generateEnvironmentVariableReference.sh
 
     - name: Use git to detect changes in the regenerated document and set generated_document_changed
       run: git diff --quiet || echo "generated_document_changed=true" >> $GITHUB_ENV

.github/workflows/internal-scripts-reference-documentation.yml

@@ -28,9 +28,8 @@ jobs:
         token: ${{ secrets.WORKFLOW_GIT_ACCESS_TOKEN }}
 
     - name: Generate scripts reference document
-      working-directory: scripts
       run: |
-        ./documentation/generateScriptReference.sh
+        ./scripts/documentation/generateScriptReference.sh
 
     - name: Use git to detect changes in the regenerated document and set generated_document_changed
       run: git diff --quiet || echo "generated_document_changed=true" >> $GITHUB_ENV

scripts/documentation/generateEnvironmentVariableReference.sh

@@ -1,26 +1,37 @@
 #!/usr/bin/env bash
 
-# Runs "appendEnvironmentVariable.sh" for every script file in the current directory and its sub directories.
+# Runs "appendEnvironmentVariable.sh" for every script file in the scripts directory and its sub directories.
+# Note: This script can be run from any directory (e.g. the repository root). It changes to the scripts directory internally.
 
 # Requires appendEnvironmentVariable.sh
 
 # Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
 set -o errexit -o pipefail
 
-## Get this "scripts" directory if not already set
+## Get this "scripts/documentation" 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.
 DOCUMENTATION_SCRIPTS_DIR=${DOCUMENTATION_SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )} # Repository directory containing the documentation generation scripts
 echo "generateEnvironmentVariablesReference: DOCUMENTATION_SCRIPTS_DIR=${DOCUMENTATION_SCRIPTS_DIR}"
 
+# Change to the scripts directory so that the output file is written there and all relative paths work correctly
+cd "${DOCUMENTATION_SCRIPTS_DIR}/.."
+
 echo "generateEnvironmentVariableReference: Generating ENVIRONMENT_VARIABLES.md..."
 
 # Clear existing markdown document
 source "${DOCUMENTATION_SCRIPTS_DIR}/appendEnvironmentVariables.sh" "clear" || exit 1
 
-# Loop through all script files in the current directory
-find . -type f -name "*.sh" | sort | while read -r scriptFile; do
+# Collect search roots: always the current scripts directory, plus ../domains if it exists
+search_roots="."
+if [ -d "../domains" ]; then
+  search_roots=". ../domains"
+fi
+
+# Loop through all script files in the current directory and domain directories
+# shellcheck disable=SC2086
+find ${search_roots} -type f -name "*.sh" | sort | while read -r scriptFile; do
   echo "generateEnvironmentVariablesReference: Searching for environment variables in ${scriptFile}"
   source "${DOCUMENTATION_SCRIPTS_DIR}/appendEnvironmentVariables.sh" "${scriptFile}" || exit 1
 done

scripts/documentation/generateScriptReference.sh

@@ -1,11 +1,21 @@
 #!/usr/bin/env bash
 
-# Generates "SCRIPTS.md" containing a reference to all scripts in this directory and its subdirectories.
+# Generates "SCRIPTS.md" containing a reference to all scripts in the scripts directory and its subdirectories.
+# Note: This script can be run from any directory (e.g. the repository root). It changes to the scripts directory internally.
 # This script was generated by Chat-GPT after some messages back and forth and then tuned manually.
 
 # Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
 set -o errexit -o pipefail
 
+## Get this "scripts/documentation" 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.
+DOCUMENTATION_SCRIPTS_DIR=${DOCUMENTATION_SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )} # Repository directory containing the documentation generation scripts
+
+# Change to the scripts directory so that the output file is written there and all relative paths work correctly
+cd "${DOCUMENTATION_SCRIPTS_DIR}/.."
+
 # Markdown file name
 markdown_file="SCRIPTS.md"
 
@@ -22,8 +32,15 @@ echo "generateScriptReference: Generating ${markdown_file}..."
   echo "-------|-----------|------------" 
 } > ${markdown_file}
 
-# Loop through all script files in the current directory
-find . -type f -name "*.sh" | sort | while read -r script_file; do
+# Collect search roots: always the current scripts directory, plus ../domains if it exists
+search_roots="."
+if [ -d "../domains" ]; then
+  search_roots=". ../domains"
+fi
+
+# Loop through all script files in the current directory and domain directories
+# shellcheck disable=SC2086
+find ${search_roots} -type f -name "*.sh" | sort | while read -r script_file; do
     # Get the description of the script file
     description=$(awk 'NR>1 && /^ *#/{sub(/^ *# ?/,""); print; exit}' "$script_file")