🩹 [Patch]: Enhance error handling and summary reporting in documentation generation (#22)

## Description

This pull request enhances the error handling and reporting for
PowerShell module documentation generation. Now, when documentation
generation fails for one or more commands, the script collects detailed
error information, summarizes the failures in a GitHub Actions step
summary, and fails the build with a clear message.

Improvements to error handling and reporting:

* Introduced a `$failedCommands` collection to track commands that fail
documentation generation, capturing their names and error details.
* After processing all commands, if any failures occurred, the script
outputs a detailed summary to the console and to the
`$env:GITHUB_STEP_SUMMARY` file, including a markdown table of failed
commands and their errors, and then fails the build with an appropriate
exit code.

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -43,6 +43,7 @@ jobs:
         with:
           Name: PSModuleTest
           WorkingDirectory: tests/srcTestRepo
+          ShowSummaryOnSuccess: true
 
       - name: Get changes
         uses: PSModule/GitHub-Script@v1

README.md

@@ -25,6 +25,7 @@ Include this action in your workflow to automatically build and structure docume
 |--------------------|-----------------------------------------------|----------|-------------|
 | `Name`             | Name of the module to document.               | No       | <Repo name> |
 | `WorkingDirectory` | Directory from which the script will execute. | No       | `.`         |
+| `ShowSummaryOnSuccess` | Show GitHub Step Summary even when all commands succeed. | No | `false` |
 
 ### Secrets
 
@@ -42,4 +43,5 @@ This action does not have defined outputs.
   with:
     Name: 'MyModule'
     WorkingDirectory: './module-directory'
+    ShowSummaryOnSuccess: true  # Optional: Show summary even on success
 ```

action.yml

@@ -13,6 +13,10 @@ inputs:
     description: The working directory where the script will run from.
     required: false
     default: '.'
+  ShowSummaryOnSuccess:
+    description: Show GitHub Step Summary even when all commands succeed.
+    required: false
+    default: 'false'
 
 runs:
   using: composite
@@ -24,6 +28,7 @@ runs:
       shell: pwsh
       env:
         GITHUB_ACTION_INPUT_Name: ${{ inputs.Name }}
+        GITHUB_ACTION_INPUT_ShowSummaryOnSuccess: ${{ inputs.ShowSummaryOnSuccess }}
       working-directory: ${{ inputs.WorkingDirectory }}
       run: |
         # Build-PSModuleDocumentation

scripts/helpers/Build-PSModuleDocumentation.ps1

@@ -26,7 +26,11 @@
 
         # Path to the folder where the documentation is outputted.
         [Parameter(Mandatory)]
-        [string] $DocsOutputFolderPath
+        [string] $DocsOutputFolderPath,
+
+        # Show GitHub Step Summary even when all commands succeed.
+        [Parameter()]
+        [bool] $ShowSummaryOnSuccess = $false
     )
 
     Write-Host "::group::Documenting module [$ModuleName]"
@@ -53,6 +57,7 @@
     $commands = $moduleInfo.ExportedCommands.Values | Where-Object { $_.CommandType -ne 'Alias' }
 
     Write-Host "::group::Build docs - Generating markdown help files for $($commands.Count) commands in [$docsOutputFolder]"
+    $commandResults = [System.Collections.Generic.List[PSObject]]::new()
     foreach ($command in $commands) {
         try {
             Write-Host "$($command.Name)" -NoNewline
@@ -66,11 +71,65 @@
             }
             $null = New-MarkdownCommandHelp @params
             Write-Host " - $($PSStyle.Foreground.Green)✓$($PSStyle.Reset)"
+            $commandResults.Add([PSCustomObject]@{
+                    CommandName = $command.Name
+                    Status      = 'Success'
+                    Error       = $null
+                    ErrorString = $null
+                })
         } catch {
             Write-Host " - $($PSStyle.Foreground.Red)✗$($PSStyle.Reset)"
-            $_
+            $commandResults.Add([PSCustomObject]@{
+                    CommandName = $command.Name
+                    Status      = 'Failed'
+                    Error       = $_
+                    ErrorString = $_.ToString()
+                })
+            Write-Error $_
         }
     }
+    Write-Host '::endgroup::'
+
+    $failedCommands = $commandResults | Where-Object { $_.Status -eq 'Failed' }
+    $successfulCommands = $commandResults | Where-Object { $_.Status -eq 'Success' }
+    $hasFailures = $failedCommands.Count -gt 0
+    $shouldShowSummary = $hasFailures -or $ShowSummaryOnSuccess
+
+    # Generate summary if there are failures OR if ShowSummaryOnSuccess is enabled
+    if ($shouldShowSummary) {
+        $statusIcon = $hasFailures ? '❌' : '✅'
+        $statusText = $hasFailures ? 'Failed' : 'Succeeded'
+        Write-Host "::group::Build docs - Documentation generation summary $statusIcon"
+
+        $successCount = $successfulCommands.Count
+        $failureCount = $failedCommands.Count
+
+        $summaryContent = @"
+# $statusIcon Documentation Build $($statusText.ToLower())
+
+| Success | Failure |
+|---------|---------|
+| $successCount | $failureCount |
+
+## Command status
+
+| Command | Status |
+|---------|--------|
+$(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" }) -join '')
+
+"@
+
+
+        $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+        Write-Host "$summaryContent"
+        Write-Host '::endgroup::'
+    }
+
+    # Fail the task if there were any failures (independent of summary display)
+    if ($hasFailures) {
+        Write-Error "Documentation generation failed for $($failedCommands.Count) command(s). See above for details."
+        exit 1
+    }
 
     Write-Host '::group::Build docs - Generated files'
     Get-ChildItem -Path $docsOutputFolder -Recurse | Select-Object -ExpandProperty FullName

scripts/main.ps1

@@ -38,6 +38,7 @@ Get-ChildItem -Path $path -Filter '*.ps1' -Recurse | Resolve-Path -Relative | Fo
 Write-Host '::group::Loading inputs'
 $env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY -replace '.+/'
 $moduleName = [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_Name) ? $env:GITHUB_REPOSITORY_NAME : $env:GITHUB_ACTION_INPUT_Name
+$showSummaryOnSuccess = $env:GITHUB_ACTION_INPUT_ShowSummaryOnSuccess -eq 'true'
 $moduleSourceFolderPath = Resolve-Path -Path 'src' | Select-Object -ExpandProperty Path
 $modulesOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/module'
 $docsOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/docs'
@@ -47,6 +48,7 @@ $params = @{
     ModuleSourceFolderPath  = $moduleSourceFolderPath
     ModulesOutputFolderPath = $modulesOutputFolderPath
     DocsOutputFolderPath    = $docsOutputFolderPath
+    ShowSummaryOnSuccess    = $showSummaryOnSuccess
 }
 
 [pscustomobject]$params | Format-List | Out-String

tests/srcTestRepo/outputs/module/PSModuleTest/PSModuleTest.psm1

@@ -24,9 +24,9 @@ Write-Verbose "[$scriptName] - [/init] - Processing folder"
 #region - From /init/initializer.ps1
 Write-Verbose "[$scriptName] - [/init/initializer.ps1] - Importing"
 
-Write-Verbose '-------------------------------' -Verbose
-Write-Verbose '---  THIS IS AN INITIALIZER ---' -Verbose
-Write-Verbose '-------------------------------' -Verbose
+Write-Verbose '-------------------------------'
+Write-Verbose '---  THIS IS AN INITIALIZER ---'
+Write-Verbose '-------------------------------'
 
 Write-Verbose "[$scriptName] - [/init/initializer.ps1] - Done"
 #endregion - From /init/initializer.ps1
@@ -190,7 +190,7 @@ Write-Verbose "[$scriptName] - [/private] - Processing folder"
 #region - From /private/Get-InternalPSModule.ps1
 Write-Verbose "[$scriptName] - [/private/Get-InternalPSModule.ps1] - Importing"
 
-Function Get-InternalPSModule {
+function Get-InternalPSModule {
     <#
         .SYNOPSIS
         Performs tests on a module.
@@ -214,7 +214,7 @@ Write-Verbose "[$scriptName] - [/private/Get-InternalPSModule.ps1] - Done"
 #region - From /private/Set-InternalPSModule.ps1
 Write-Verbose "[$scriptName] - [/private/Set-InternalPSModule.ps1] - Importing"
 
-Function Set-InternalPSModule {
+function Set-InternalPSModule {
     <#
         .SYNOPSIS
         Performs tests on a module.
@@ -379,9 +379,9 @@ Write-Verbose "[$scriptName] - [/public] - Done"
 #region - From /finally.ps1
 Write-Verbose "[$scriptName] - [/finally.ps1] - Importing"
 
-Write-Verbose '------------------------------' -Verbose
-Write-Verbose '---  THIS IS A LAST LOADER ---' -Verbose
-Write-Verbose '------------------------------' -Verbose
+Write-Verbose '------------------------------'
+Write-Verbose '---  THIS IS A LAST LOADER ---'
+Write-Verbose '------------------------------'
 Write-Verbose "[$scriptName] - [/finally.ps1] - Done"
 #endregion - From /finally.ps1
 

tests/srcTestRepo/outputs/module/PSModuleTest/scripts/loader.ps1

@@ -1,3 +1,3 @@
-Write-Verbose '-------------------------' -Verbose
-Write-Verbose '---  THIS IS A LOADER ---' -Verbose
-Write-Verbose '-------------------------' -Verbose
+Write-Verbose '-------------------------'
+Write-Verbose '---  THIS IS A LOADER ---'
+Write-Verbose '-------------------------'