From 0c2e14dd7c761221789e184d3cb3b7108f710084 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 08:42:33 +0200 Subject: [PATCH 1/6] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Enhance=20error?= =?UTF-8?q?=20handling=20and=20summary=20reporting=20in=20documentation=20?= =?UTF-8?q?generation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../helpers/Build-PSModuleDocumentation.ps1 | 50 ++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index 1b33e3b..b091f87 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/scripts/helpers/Build-PSModuleDocumentation.ps1 @@ -53,6 +53,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 = @() foreach ($command in $commands) { try { Write-Host "$($command.Name)" -NoNewline @@ -68,8 +69,55 @@ Write-Host " - $($PSStyle.Foreground.Green)✓$($PSStyle.Reset)" } catch { Write-Host " - $($PSStyle.Foreground.Red)✗$($PSStyle.Reset)" - $_ + $failedCommands += [PSCustomObject]@{ + CommandName = $command.Name + Error = $_ + ErrorString = $_.ToString() + } + Write-Error $_ + } + } + + # 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 + +Failed to generate documentation for **$($failedCommands.Count)** command(s) out of **$($commands.Count)** total. + +## Failed Commands + +| Command | Error | +|---------|-------| +"@ + foreach ($failed in $failedCommands) { + # Escape pipe characters in error messages for markdown table + $errorMsg = $failed.ErrorString -replace '\|', '\|' -replace "`r`n", '
' -replace "`n", '
' + $summaryContent += "`n| ``$($failed.CommandName)`` | $errorMsg |" } + + $summaryContent += @" + + +## Summary + +- :white_check_mark: Successful: **$($commands.Count - $failedCommands.Count)** +- :x: Failed: **$($failedCommands.Count)** + +"@ + $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append + + Write-Host '::endgroup::' + Write-Error "Documentation generation failed for $($failedCommands.Count) command(s). See above for details." + exit 1 } Write-Host '::group::Build docs - Generated files' From d1a21e35c7ad7abcf36da9a5f886d7f2f488ec96 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 09:42:51 +0200 Subject: [PATCH 2/6] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Add=20ShowSummary?= =?UTF-8?q?OnSuccess=20input=20to=20control=20summary=20display=20in=20doc?= =?UTF-8?q?umentation=20generation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 + action.yml | 5 ++ .../helpers/Build-PSModuleDocumentation.ps1 | 79 +++++++++++-------- scripts/main.ps1 | 2 + 4 files changed, 53 insertions(+), 35 deletions(-) diff --git a/README.md b/README.md index 9fb3dfe..57aea3f 100644 --- a/README.md +++ b/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 | | | `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 ``` diff --git a/action.yml b/action.yml index e5b49d8..1cd094f 100644 --- a/action.yml +++ b/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 diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index b091f87..62c6b4c 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/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", '
' -replace "`n", '
' - $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 } diff --git a/scripts/main.ps1 b/scripts/main.ps1 index 68e1b2b..6557d1c 100644 --- a/scripts/main.ps1 +++ b/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 From 89f80b8a189a91b555f0c74ca6423aff2deca367 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 09:44:07 +0200 Subject: [PATCH 3/6] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Enable=20ShowSumm?= =?UTF-8?q?aryOnSuccess=20in=20Action-Test=20workflow=20to=20control=20sum?= =?UTF-8?q?mary=20display?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/Action-Test.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/Action-Test.yml b/.github/workflows/Action-Test.yml index 23df0ab..eafd48d 100644 --- a/.github/workflows/Action-Test.yml +++ b/.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 From ca42ebabff6cf6784f9a43efdc5c92197bfce674 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 10:01:21 +0200 Subject: [PATCH 4/6] Fix formatting in summary generation for command status output --- scripts/helpers/Build-PSModuleDocumentation.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index 62c6b4c..ad4e8e4 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/scripts/helpers/Build-PSModuleDocumentation.ps1 @@ -115,7 +115,7 @@ | Command | Status | |---------|--------| -$($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" } -join '') +$(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" }) -join '') "@ From 82cc0c9690d20da26f9864e509d687a8a5ad63f5 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 10:12:46 +0200 Subject: [PATCH 5/6] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Add=20additional?= =?UTF-8?q?=20logging=20for=20summary=20content=20in=20documentation=20bui?= =?UTF-8?q?ld=20process?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- scripts/helpers/Build-PSModuleDocumentation.ps1 | 2 ++ 1 file changed, 2 insertions(+) diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index ad4e8e4..88de292 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/scripts/helpers/Build-PSModuleDocumentation.ps1 @@ -119,7 +119,9 @@ $(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |` "@ + $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append + Write-Host "$summaryContent" Write-Host '::endgroup::' } From e4e0651e94ca3c9fad96ef7a54e73fda1171576f Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Tue, 7 Oct 2025 10:13:51 +0200 Subject: [PATCH 6/6] =?UTF-8?q?=F0=9F=A9=B9=20[Patch]:=20Remove=20redundan?= =?UTF-8?q?t=20-Verbose=20flag=20from=20Write-Verbose=20statements=20in=20?= =?UTF-8?q?initializer=20and=20loader=20scripts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../module/PSModuleTest/PSModuleTest.psm1 | 16 ++++++++-------- .../module/PSModuleTest/scripts/loader.ps1 | 6 +++--- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/tests/srcTestRepo/outputs/module/PSModuleTest/PSModuleTest.psm1 b/tests/srcTestRepo/outputs/module/PSModuleTest/PSModuleTest.psm1 index fd0f1be..3652a48 100644 --- a/tests/srcTestRepo/outputs/module/PSModuleTest/PSModuleTest.psm1 +++ b/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 diff --git a/tests/srcTestRepo/outputs/module/PSModuleTest/scripts/loader.ps1 b/tests/srcTestRepo/outputs/module/PSModuleTest/scripts/loader.ps1 index 29ad42f..973735a 100644 --- a/tests/srcTestRepo/outputs/module/PSModuleTest/scripts/loader.ps1 +++ b/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 '-------------------------'