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/appendEnvironmentVariables.sh

@@ -8,8 +8,8 @@
 # Fail on any error ("-e" = exit on first error, "-o pipefail" exist on errors within piped commands)
 set -o errexit -o pipefail
 
-# Markdown file name
-markdownFile="ENVIRONMENT_VARIABLES.md"
+# Markdown file name (can be overridden by second argument)
+markdownFile="${2:-ENVIRONMENT_VARIABLES.md}"
 
 # If the first command line option is "clear" (instead of a filename) then delete the markdown file.
 if [[ "$1" == "clear" ]] ; then

scripts/documentation/generateEnvironmentVariableReference.sh

@@ -1,28 +1,32 @@
 #!/usr/bin/env bash
 
-# Runs "appendEnvironmentVariable.sh" for every script file in the current directory and its sub directories.
+# Runs "appendEnvironmentVariables.sh" for every script file in all directories and subdirectories.
+# Note: This script can be run from any directory (e.g. the repository root). It changes to the repository root internally.
 
-# Requires appendEnvironmentVariable.sh
+# Requires appendEnvironmentVariables.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}"
+echo "generateEnvironmentVariableReference: DOCUMENTATION_SCRIPTS_DIR=${DOCUMENTATION_SCRIPTS_DIR}"
 
-echo "generateEnvironmentVariableReference: Generating ENVIRONMENT_VARIABLES.md..."
+# Change to the repository root so that the output file is written there and all relative paths work correctly
+cd "${DOCUMENTATION_SCRIPTS_DIR}/../.."
+
+echo "generateEnvironmentVariableReference: Generating scripts/ENVIRONMENT_VARIABLES.md..."
 
 # Clear existing markdown document
-source "${DOCUMENTATION_SCRIPTS_DIR}/appendEnvironmentVariables.sh" "clear" || exit 1
+source "${DOCUMENTATION_SCRIPTS_DIR}/appendEnvironmentVariables.sh" "clear" "scripts/ENVIRONMENT_VARIABLES.md" || exit 1
 
-# Loop through all script files in the current directory
+# Loop through all script files in all directories from the repository root
 find . -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
+  echo "generateEnvironmentVariableReference: Searching for environment variables in ${scriptFile}"
+  source "${DOCUMENTATION_SCRIPTS_DIR}/appendEnvironmentVariables.sh" "${scriptFile}" "scripts/ENVIRONMENT_VARIABLES.md" || exit 1
 done
 
 echo "generateEnvironmentVariableReference: Successfully generated ENVIRONMENT_VARIABLES.md."

scripts/documentation/generateScriptReference.sh

@@ -1,13 +1,23 @@
 #!/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 all directories and subdirectories.
+# Note: This script can be run from any directory (e.g. the repository root). It changes to the repository root 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
 
-# Markdown file name
-markdown_file="SCRIPTS.md"
+## 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 repository root so that the output file is written there and all relative paths work correctly
+cd "${DOCUMENTATION_SCRIPTS_DIR}/../.."
+
+# Markdown file name (written to scripts directory)
+markdown_file="scripts/SCRIPTS.md"
 
 echo "generateScriptReference: Generating ${markdown_file}..."
 
@@ -22,7 +32,7 @@ echo "generateScriptReference: Generating ${markdown_file}..."
   echo "-------|-----------|------------" 
 } > ${markdown_file}
 
-# Loop through all script files in the current directory
+# Loop through all script files in all directories from the repository root
 find . -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")