🩹 [Patch]: Enhance error handling and summary reporting in documentation generation

.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