generateScriptReference.sh

#!/usr/bin/env bash

# Generates "SCRIPTS.md" containing a reference to all scripts in all directories and subdirectories.
# Note: This script is intended to be run from the repository root.
# 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.
SCRIPT_NAME="generateScriptReference"
DOCUMENTATION_SCRIPTS_DIR=${DOCUMENTATION_SCRIPTS_DIR:-$( CDPATH=. cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd -P )} # Repository directory containing the documentation generation scripts

# Markdown file name (written to scripts directory)
markdown_file="./SCRIPTS.md"

echo "${SCRIPT_NAME}: Generating ${markdown_file}..."

{ 
  echo "# Scripts Reference" 
  echo ""
  echo "This document serves as a reference for all scripts in the repository and its subdirectories."
  echo "It provides a table listing each script file and its corresponding description found in the first comment line."
  echo "This file was generated with the script [${SCRIPT_NAME}.sh](./scripts/documentation/${SCRIPT_NAME}.sh)."
  echo ""
  echo "Script | Directory | Description"
  echo "------ | --------- | -----------" 
} > ${markdown_file}

# Loop through all script files in the current directory and all subdirectories, excluding "temp" and ".github" directories
find -L . \( -type d -name "temp" -o -type d -name ".github" \) -prune -o -type f -name "*.sh" -print | sort | while read -r script_file; do
    # Get the description of the script file
    description=$(awk 'NR>1 && /^ *#/{sub(/^ *# ?/,""); print; exit}' "$script_file")

    # Extract the script file name without the path
    filename=$(basename "$script_file")
    
    # Extract the script file path without the name
    pathname=$(dirname "$script_file")
    last_path_segment=$(basename "$pathname")
    
    # Create a link to the script file in the table
    link="[${filename}](${script_file})"
    
    # Add the script file and its description to the Markdown table
    echo "${link} | ${last_path_segment%%.} | ${description//|/\\|}" >> ${markdown_file}
done

echo "${SCRIPT_NAME}: Successfully generated ${markdown_file}."