🩹 [Patch]: Group successful and failed doc generation (#26)

## Description

This pull request reorganizes the GitHub Actions workflow, improves
input handling and environment variable usage in the action, and
enhances the summary output for PowerShell module documentation
commands. The most notable changes are the restructuring of workflow
jobs to support different summary behaviors, improved input/environment
variable consistency, and more detailed step summaries.

- Fixes PSModule/Process-PSModule#229

**GitHub Actions workflow improvements:**

* The `.github/workflows/Action-Test.yml` workflow now separates
artifact upload into its own `UploadArtifact` job, and introduces two
test jobs: `ActionTestDefault` (without always showing summary) and
`ActionTestWithSummary` (always shows summary on success). This allows
testing both behaviors and ensures artifacts are available before
running tests.
[[1]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4L26-R27)
[[2]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4R44-L49)
[[3]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4R69-R87)

**Action input and environment variable handling:**

* The `action.yml` file reorders the `inputs` section for clarity, and
environment variables passed to scripts now use a consistent
`DOCUMENT_PSMODULE_INPUT_*` naming scheme instead of the previous
`GITHUB_ACTION_INPUT_*`.
[[1]](diffhunk://#diff-1243c5424efaaa19bd8e813c5e6f6da46316e63761421b3e5f5c8ced9a36e6b6L12-R19)
[[2]](diffhunk://#diff-1243c5424efaaa19bd8e813c5e6f6da46316e63761421b3e5f5c8ced9a36e6b6L30-R31)
* The `scripts/main.ps1` script now accepts `Name` and
`ShowSummaryOnSuccess` as parameters, defaulting to the new environment
variable names, and updates how these values are handled and passed to
helper scripts.
[[1]](diffhunk://#diff-dc2e5a659836b1b73abb03421c567f5018c2755677c4a0aa764cb26117b68011L6-R19)
[[2]](diffhunk://#diff-dc2e5a659836b1b73abb03421c567f5018c2755677c4a0aa764cb26117b68011L28-R30)
[[3]](diffhunk://#diff-dc2e5a659836b1b73abb03421c567f5018c2755677c4a0aa764cb26117b68011L40-R51)

**Summary output enhancements:**

* The `Build-PSModuleDocumentation.ps1` script changes the summary
section to use collapsible `<details>` blocks for failed and succeeded
commands, making the output clearer and easier to navigate in GitHub
step summaries.
[[1]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L98-R98)
[[2]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L114-R146)

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -23,8 +23,8 @@ permissions:
   statuses: write # to create commit status
 
 jobs:
-  ActionTestDefault:
-    name: Action-Test - [Default]
+  UploadArtifact:
+    name: Upload Artifact
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repo
@@ -41,12 +41,22 @@ jobs:
           if-no-files-found: error
           retention-days: 1
 
+  ActionTestDefault:
+    name: Action-Test - [Default]
+    runs-on: ubuntu-latest
+    needs: UploadArtifact
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
       - name: Action-Test
         uses: ./
         with:
           Name: PSModuleTest
           WorkingDirectory: tests/srcTestRepo
-          ShowSummaryOnSuccess: true
 
       - name: Lint documentation
         uses: super-linter/super-linter/[email protected]
@@ -56,3 +66,22 @@ jobs:
           VALIDATE_NATURAL_LANGUAGE: true
           VALIDATE_ALL_CODEBASE: true
           USE_FIND_ALGORITHM: true
+
+  ActionTestWithSummary:
+    name: Action-Test - [With Summary]
+    runs-on: ubuntu-latest
+    needs: UploadArtifact
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
+
+
+      - name: Action-Test
+        uses: ./
+        with:
+          Name: PSModuleTest
+          WorkingDirectory: tests/srcTestRepo
+          ShowSummaryOnSuccess: true

action.yml

@@ -9,14 +9,14 @@ inputs:
   Name:
     description: Name of the module to process.
     required: false
-  WorkingDirectory:
-    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'
+  WorkingDirectory:
+    description: The working directory where the script will run from.
+    required: false
+    default: '.'
 
 runs:
   using: composite
@@ -27,8 +27,8 @@ runs:
     - name: Document-PSModule
       shell: pwsh
       env:
-        GITHUB_ACTION_INPUT_Name: ${{ inputs.Name }}
-        GITHUB_ACTION_INPUT_ShowSummaryOnSuccess: ${{ inputs.ShowSummaryOnSuccess }}
+        DOCUMENT_PSMODULE_INPUT_Name: ${{ inputs.Name }}
+        DOCUMENT_PSMODULE_INPUT_ShowSummaryOnSuccess: ${{ inputs.ShowSummaryOnSuccess }}
       working-directory: ${{ inputs.WorkingDirectory }}
       run: |
         # Build-PSModuleDocumentation

scripts/helpers/Build-PSModuleDocumentation.ps1

@@ -1,10 +1,10 @@
 function Build-PSModuleDocumentation {
     <#
-    .SYNOPSIS
-    Builds a module.
+        .SYNOPSIS
+        Builds a module.
 
-    .DESCRIPTION
-    Builds a module.
+        .DESCRIPTION
+        Builds a module.
     #>
     [CmdletBinding()]
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
@@ -95,7 +95,7 @@
     $hasFailures = $failedCommands.Count -gt 0
     $shouldShowSummary = $hasFailures -or $ShowSummaryOnSuccess
 
-    # Generate summary if there are failures OR if ShowSummaryOnSuccess is enabled
+    # Generate summary if ShowSummaryOnSuccess is enabled
     if ($shouldShowSummary) {
         $statusIcon = $hasFailures ? '❌' : '✅'
         $statusText = $hasFailures ? 'Failed' : 'Succeeded'
@@ -111,13 +111,39 @@
 |---------|---------|
 | $successCount | $failureCount |
 
-## Command status
+"@
+
+        if ($failedCommands) {
+            $summaryContent += @"
+
+<details><summary>Failed</summary>
+
+<p>
+
+$(($failedCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join '')
+
+</p>
+
+</details>
+
+"@
+        }
+
+        if ($successfulCommands) {
+            $summaryContent += @"
+
+<details><summary>Succeeded</summary>
 
-| Command | Status |
-|---------|--------|
-$(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" }) -join '')
+<p>
+
+$(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join '')
+
+</p>
+
+</details>
 
 "@
+        }
 
 
         $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append

scripts/main.ps1

@@ -3,18 +3,20 @@
     Justification = 'Want to just write to the console, not the pipeline.'
 )]
 [CmdletBinding()]
-param()
+param(
+    [string]$Name = $env:DOCUMENT_PSMODULE_INPUT_Name,
+    [bool]$ShowSummaryOnSuccess = $env:DOCUMENT_PSMODULE_INPUT_ShowSummaryOnSuccess -eq 'true'
+)
 
 $PSStyle.OutputRendering = 'Ansi'
 
 'Microsoft.PowerShell.PlatyPS' | ForEach-Object {
-    $name = $_
-    Write-Output "Installing module: $name"
+    Write-Output "Installing module: $_"
     $retryCount = 5
     $retryDelay = 10
     for ($i = 0; $i -lt $retryCount; $i++) {
         try {
-            Install-PSResource -Name $name -WarningAction SilentlyContinue -TrustRepository -Repository PSGallery
+            Install-PSResource -Name $_ -WarningAction SilentlyContinue -TrustRepository -Repository PSGallery
             break
         } catch {
             Write-Warning "Installation of $($psResourceParams.Name) failed with error: $_"
@@ -25,7 +27,7 @@ $PSStyle.OutputRendering = 'Ansi'
             Start-Sleep -Seconds $retryDelay
         }
     }
-    Import-Module -Name $name
+    Import-Module -Name $_
 }
 
 $path = (Join-Path -Path $PSScriptRoot -ChildPath 'helpers') | Get-Item | Resolve-Path -Relative
@@ -37,18 +39,16 @@ 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'
 
 $params = @{
-    ModuleName              = $moduleName
+    ModuleName              = [string]::IsNullOrEmpty($Name) ? $env:GITHUB_REPOSITORY_NAME : $Name
     ModuleSourceFolderPath  = $moduleSourceFolderPath
     ModulesOutputFolderPath = $modulesOutputFolderPath
     DocsOutputFolderPath    = $docsOutputFolderPath
-    ShowSummaryOnSuccess    = $showSummaryOnSuccess
+    ShowSummaryOnSuccess    = $ShowSummaryOnSuccess
 }
 
 [pscustomobject]$params | Format-List | Out-String