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 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 1b33e3b..88de292 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,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 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 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 '-------------------------'