Debian Codegraph @

scripts/generate-service-config-docs.sh

raw
1 #!/usr/bin/env bash
2
3 # Enable strict error handling: exit on any error to prevent unexpected behavior.
4 set -e
5
6 # Function: generate_docs
7 # Purpose: Generates Markdown documentation for a given service and saves it to the docs/services/<category>/<service> directory.
8 # Arguments:
9 # $1: The name of the service to generate documentation for.
10 # $2: The category of the service.
11 function generate_docs() {
12 # Store the service name from the first argument.
13 SERVICE=$1
14 # Store the category name from the second argument.
15 CATEGORY=$2
16 # Define the output path for the service's documentation file (docs/services/<category>/<service>/config.md).
17 DOCSPATH="$(dirname "$(dirname "$0")")/docs/services/$CATEGORY/$SERVICE"
18 # Print a status message indicating which service is being processed, using ANSI color for visibility.
19 echo -en "Creating docs for \e[96m$CATEGORY/$SERVICE\e[0m... "
20 # Create the service's documentation directory if it doesn't exist, ensuring the output path is ready.
21 mkdir -p "$DOCSPATH"
22 # Run the shoutrrr CLI's 'docs' command to generate Markdown documentation for the service.
23 # The command uses 'go run' to execute the main package in ./shoutrrr, passing the service name and Markdown format flag.
24 # Output is redirected to config.md in the service's docs directory.
25 if go run "$(dirname "$(dirname "$0")")/shoutrrr" docs -f markdown "$SERVICE" > "$DOCSPATH"/config.md; then
26 # Print success message if the documentation was generated successfully.
27 echo -e "Done!"
28 fi
29 }
30
31 # Define the path to the services directory, relative to the repository root.
32 # Use dirname to get the repository root from the script's location ($0 is the script path).
33 SERVICES_PATH="$(dirname "$(dirname "$0")")/pkg/services"
34
35 # Check if a specific service name was provided as a command-line argument.
36 if [[ -n "$1" ]]; then
37 # If an argument is provided, find the service directory and extract category.
38 SERVICE_ARG=$1
39 SERVICE_DIR=$(find "$SERVICES_PATH" -type d -name "$SERVICE_ARG" | head -1)
40 if [[ -z "$SERVICE_DIR" ]]; then
41 echo "Service $SERVICE_ARG not found"
42 exit 1
43 fi
44 CATEGORY=$(basename "$(dirname "$SERVICE_DIR")")
45 generate_docs "$SERVICE_ARG" "$CATEGORY"
46 exit 0
47 fi
48
49 # Debug: Print the services path being used to help diagnose issues.
50 echo "Debug: Checking services path: $SERVICES_PATH"
51
52 # Check for the existence of service directories in pkg/services/.
53 # The 'compgen -G' command tests if the glob pattern matches any files or directories.
54 # If no service directories are found, print an error and exit to avoid processing invalid entries.
55 if ! compgen -G "$SERVICES_PATH/*" > /dev/null; then
56 echo "No service directories found in $SERVICES_PATH"
57 # Debug: List the contents of the directory to diagnose why the glob failed.
58 echo "Debug: Contents of $SERVICES_PATH:"
59 ls -la "$SERVICES_PATH" || echo "Error: Cannot list $SERVICES_PATH"
60 exit 1
61 fi
62
63 # Iterate over all category directories in the pkg/services/ directory.
64 for CATEGORY_DIR in "$SERVICES_PATH"/*; do
65 # Skip any entry that is not a directory.
66 if [[ ! -d "$CATEGORY_DIR" ]]; then
67 continue
68 fi
69 # Extract the category name.
70 CATEGORY=$(basename "$CATEGORY_DIR")
71 # Iterate over service directories in the category.
72 for SERVICE_DIR in "$CATEGORY_DIR"/*; do
73 # Skip any entry that is not a directory.
74 if [[ ! -d "$SERVICE_DIR" ]]; then
75 continue
76 fi
77 # Extract the service name.
78 SERVICE=$(basename "$SERVICE_DIR")
79 # Skip specific services ('standard', 'xmpp', and directories named 'mocks').
80 if [[ "$SERVICE" == "standard" ]] || [[ "$SERVICE" == "xmpp" ]] || [[ "$SERVICE" == "mocks" ]]; then
81 continue
82 fi
83 # Debug: Print the service being processed.
84 echo "Debug: Processing service: $CATEGORY/$SERVICE"
85 # Call the generate_docs function.
86 generate_docs "$SERVICE" "$CATEGORY"
87 done
88 done