Skip to content

Commit adc0da7

Browse files
MariusStorhaugMariusStorhaug
authored
🩹 [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.
1 parent ffe09c2 commit adc0da7

7 files changed

Lines changed: 82 additions & 13 deletions

File tree

‎.github/workflows/Action-Test.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ jobs:
4343
with:
4444
Name: PSModuleTest
4545
WorkingDirectory: tests/srcTestRepo
46+
ShowSummaryOnSuccess: true
4647

4748
- name: Get changes
4849
uses: PSModule/GitHub-Script@v1

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ Include this action in your workflow to automatically build and structure docume
2525
|--------------------|-----------------------------------------------|----------|-------------|
2626
| `Name` | Name of the module to document. | No | <Repo name> |
2727
| `WorkingDirectory` | Directory from which the script will execute. | No | `.` |
28+
| `ShowSummaryOnSuccess` | Show GitHub Step Summary even when all commands succeed. | No | `false` |
2829

2930
### Secrets
3031

@@ -42,4 +43,5 @@ This action does not have defined outputs.
4243
with:
4344
Name: 'MyModule'
4445
WorkingDirectory: './module-directory'
46+
ShowSummaryOnSuccess: true # Optional: Show summary even on success
4547
```

‎action.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ inputs:
1313
description: The working directory where the script will run from.
1414
required: false
1515
default: '.'
16+
ShowSummaryOnSuccess:
17+
description: Show GitHub Step Summary even when all commands succeed.
18+
required: false
19+
default: 'false'
1620

1721
runs:
1822
using: composite
@@ -24,6 +28,7 @@ runs:
2428
shell: pwsh
2529
env:
2630
GITHUB_ACTION_INPUT_Name: ${{ inputs.Name }}
31+
GITHUB_ACTION_INPUT_ShowSummaryOnSuccess: ${{ inputs.ShowSummaryOnSuccess }}
2732
working-directory: ${{ inputs.WorkingDirectory }}
2833
run: |
2934
# Build-PSModuleDocumentation

‎scripts/helpers/Build-PSModuleDocumentation.ps1‎

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,11 @@
2626

2727
# Path to the folder where the documentation is outputted.
2828
[Parameter(Mandatory)]
29-
[string] $DocsOutputFolderPath
29+
[string] $DocsOutputFolderPath,
30+
31+
# Show GitHub Step Summary even when all commands succeed.
32+
[Parameter()]
33+
[bool] $ShowSummaryOnSuccess = $false
3034
)
3135

3236
Write-Host "::group::Documenting module [$ModuleName]"
@@ -53,6 +57,7 @@
5357
$commands = $moduleInfo.ExportedCommands.Values | Where-Object { $_.CommandType -ne 'Alias' }
5458

5559
Write-Host "::group::Build docs - Generating markdown help files for $($commands.Count) commands in [$docsOutputFolder]"
60+
$commandResults = [System.Collections.Generic.List[PSObject]]::new()
5661
foreach ($command in $commands) {
5762
try {
5863
Write-Host "$($command.Name)" -NoNewline
@@ -66,11 +71,65 @@
6671
}
6772
$null = New-MarkdownCommandHelp @params
6873
Write-Host " - $($PSStyle.Foreground.Green)✓$($PSStyle.Reset)"
74+
$commandResults.Add([PSCustomObject]@{
75+
CommandName = $command.Name
76+
Status = 'Success'
77+
Error = $null
78+
ErrorString = $null
79+
})
6980
} catch {
7081
Write-Host " - $($PSStyle.Foreground.Red)✗$($PSStyle.Reset)"
71-
$_
82+
$commandResults.Add([PSCustomObject]@{
83+
CommandName = $command.Name
84+
Status = 'Failed'
85+
Error = $_
86+
ErrorString = $_.ToString()
87+
})
88+
Write-Error $_
7289
}
7390
}
91+
Write-Host '::endgroup::'
92+
93+
$failedCommands = $commandResults | Where-Object { $_.Status -eq 'Failed' }
94+
$successfulCommands = $commandResults | Where-Object { $_.Status -eq 'Success' }
95+
$hasFailures = $failedCommands.Count -gt 0
96+
$shouldShowSummary = $hasFailures -or $ShowSummaryOnSuccess
97+
98+
# Generate summary if there are failures OR if ShowSummaryOnSuccess is enabled
99+
if ($shouldShowSummary) {
100+
$statusIcon = $hasFailures ? '❌' : '✅'
101+
$statusText = $hasFailures ? 'Failed' : 'Succeeded'
102+
Write-Host "::group::Build docs - Documentation generation summary $statusIcon"
103+
104+
$successCount = $successfulCommands.Count
105+
$failureCount = $failedCommands.Count
106+
107+
$summaryContent = @"
108+
# $statusIcon Documentation Build $($statusText.ToLower())
109+
110+
| Success | Failure |
111+
|---------|---------|
112+
| $successCount | $failureCount |
113+
114+
## Command status
115+
116+
| Command | Status |
117+
|---------|--------|
118+
$(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" }) -join '')
119+
120+
"@
121+
122+
123+
$summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
124+
Write-Host "$summaryContent"
125+
Write-Host '::endgroup::'
126+
}
127+
128+
# Fail the task if there were any failures (independent of summary display)
129+
if ($hasFailures) {
130+
Write-Error "Documentation generation failed for $($failedCommands.Count) command(s). See above for details."
131+
exit 1
132+
}
74133

75134
Write-Host '::group::Build docs - Generated files'
76135
Get-ChildItem -Path $docsOutputFolder -Recurse | Select-Object -ExpandProperty FullName

‎scripts/main.ps1‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,6 +38,7 @@ Get-ChildItem -Path $path -Filter '*.ps1' -Recurse | Resolve-Path -Relative | Fo
3838
Write-Host '::group::Loading inputs'
3939
$env:GITHUB_REPOSITORY_NAME = $env:GITHUB_REPOSITORY -replace '.+/'
4040
$moduleName = [string]::IsNullOrEmpty($env:GITHUB_ACTION_INPUT_Name) ? $env:GITHUB_REPOSITORY_NAME : $env:GITHUB_ACTION_INPUT_Name
41+
$showSummaryOnSuccess = $env:GITHUB_ACTION_INPUT_ShowSummaryOnSuccess -eq 'true'
4142
$moduleSourceFolderPath = Resolve-Path -Path 'src' | Select-Object -ExpandProperty Path
4243
$modulesOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/module'
4344
$docsOutputFolderPath = Join-Path -Path . -ChildPath 'outputs/docs'
@@ -47,6 +48,7 @@ $params = @{
4748
ModuleSourceFolderPath = $moduleSourceFolderPath
4849
ModulesOutputFolderPath = $modulesOutputFolderPath
4950
DocsOutputFolderPath = $docsOutputFolderPath
51+
ShowSummaryOnSuccess = $showSummaryOnSuccess
5052
}
5153

5254
[pscustomobject]$params | Format-List | Out-String

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

Lines changed: 8 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -24,9 +24,9 @@ Write-Verbose "[$scriptName] - [/init] - Processing folder"
2424
#region - From /init/initializer.ps1
2525
Write-Verbose "[$scriptName] - [/init/initializer.ps1] - Importing"
2626

27-
Write-Verbose '-------------------------------' -Verbose
28-
Write-Verbose '--- THIS IS AN INITIALIZER ---' -Verbose
29-
Write-Verbose '-------------------------------' -Verbose
27+
Write-Verbose '-------------------------------'
28+
Write-Verbose '--- THIS IS AN INITIALIZER ---'
29+
Write-Verbose '-------------------------------'
3030

3131
Write-Verbose "[$scriptName] - [/init/initializer.ps1] - Done"
3232
#endregion - From /init/initializer.ps1
@@ -190,7 +190,7 @@ Write-Verbose "[$scriptName] - [/private] - Processing folder"
190190
#region - From /private/Get-InternalPSModule.ps1
191191
Write-Verbose "[$scriptName] - [/private/Get-InternalPSModule.ps1] - Importing"
192192

193-
Function Get-InternalPSModule {
193+
function Get-InternalPSModule {
194194
<#
195195
.SYNOPSIS
196196
Performs tests on a module.
@@ -214,7 +214,7 @@ Write-Verbose "[$scriptName] - [/private/Get-InternalPSModule.ps1] - Done"
214214
#region - From /private/Set-InternalPSModule.ps1
215215
Write-Verbose "[$scriptName] - [/private/Set-InternalPSModule.ps1] - Importing"
216216

217-
Function Set-InternalPSModule {
217+
function Set-InternalPSModule {
218218
<#
219219
.SYNOPSIS
220220
Performs tests on a module.
@@ -379,9 +379,9 @@ Write-Verbose "[$scriptName] - [/public] - Done"
379379
#region - From /finally.ps1
380380
Write-Verbose "[$scriptName] - [/finally.ps1] - Importing"
381381

382-
Write-Verbose '------------------------------' -Verbose
383-
Write-Verbose '--- THIS IS A LAST LOADER ---' -Verbose
384-
Write-Verbose '------------------------------' -Verbose
382+
Write-Verbose '------------------------------'
383+
Write-Verbose '--- THIS IS A LAST LOADER ---'
384+
Write-Verbose '------------------------------'
385385
Write-Verbose "[$scriptName] - [/finally.ps1] - Done"
386386
#endregion - From /finally.ps1
387387

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

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
Write-Verbose '-------------------------' -Verbose
2-
Write-Verbose '--- THIS IS A LOADER ---' -Verbose
3-
Write-Verbose '-------------------------' -Verbose
1+
Write-Verbose '-------------------------'
2+
Write-Verbose '--- THIS IS A LOADER ---'
3+
Write-Verbose '-------------------------'

0 commit comments

Comments
 (0)