🩹 [Patch]: Add ShowSummaryOnSuccess input to control summary display in documentation generation

Author: MariusStorhaug

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,7 +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]"
-    $failedCommands = @()
+    $commandResults = [System.Collections.Generic.List[PSObject]]::new()
     foreach ($command in $commands) {
         try {
             Write-Host "$($command.Name)" -NoNewline
@@ -67,55 +71,60 @@
             }
             $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)"
-            $failedCommands += [PSCustomObject]@{
-                CommandName = $command.Name
-                Error       = $_
-                ErrorString = $_.ToString()
-            }
+            $commandResults.Add([PSCustomObject]@{
+                    CommandName = $command.Name
+                    Status      = 'Failed'
+                    Error       = $_
+                    ErrorString = $_.ToString()
+                })
             Write-Error $_
         }
     }
+    Write-Host '::endgroup::'
 
-    # If there were failures, generate a summary and fail the task
-    if ($failedCommands.Count -gt 0) {
-        Write-Host '::endgroup::'
-        Write-Host '::group::Build docs - Failed commands summary'
-        Write-Host "$($PSStyle.Foreground.Red)Failed to generate documentation for $($failedCommands.Count) command(s):$($PSStyle.Reset)"
-        foreach ($failed in $failedCommands) {
-            Write-Host "  $($PSStyle.Foreground.Red)✗$($PSStyle.Reset) $($failed.CommandName)"
-            Write-Host "    Error: $($failed.ErrorString)" -ForegroundColor Red
-        }
-
-        $summaryContent = @"
-# :x: Documentation Build Failed
+    $failedCommands = $commandResults | Where-Object { $_.Status -eq 'Failed' }
+    $successfulCommands = $commandResults | Where-Object { $_.Status -eq 'Success' }
+    $hasFailures = $failedCommands.Count -gt 0
+    $shouldShowSummary = $hasFailures -or $ShowSummaryOnSuccess
 
-Failed to generate documentation for **$($failedCommands.Count)** command(s) out of **$($commands.Count)** total.
+    # 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"
 
-## Failed Commands
+        $successCount = $successfulCommands.Count
+        $failureCount = $failedCommands.Count
 
-| Command | Error |
-|---------|-------|
-"@
-        foreach ($failed in $failedCommands) {
-            # Escape pipe characters in error messages for markdown table
-            $errorMsg = $failed.ErrorString -replace '\|', '\|' -replace "`r`n", '<br>' -replace "`n", '<br>'
-            $summaryContent += "`n| ``$($failed.CommandName)`` | $errorMsg |"
-        }
-
-        $summaryContent += @"
+        $summaryContent = @"
+# $statusIcon Documentation Build $($statusText.ToLower())
 
+| Success | Failure |
+|---------|---------|
+| $successCount | $failureCount |
 
-## Summary
+## Command status
 
-- :white_check_mark: Successful: **$($commands.Count - $failedCommands.Count)**
-- :x: Failed: **$($failedCommands.Count)**
+| Command | Status |
+|---------|--------|
+$($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" } -join '')
 
 "@
-        $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
 
+        $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
         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
     }

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