diff --git a/.github/workflows/Action-Test.yml b/.github/workflows/Action-Test.yml index 2191713..60f3a9e 100644 --- a/.github/workflows/Action-Test.yml +++ b/.github/workflows/Action-Test.yml @@ -23,36 +23,65 @@ 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 - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: persist-credentials: false fetch-depth: 0 - name: Upload module artifact - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@v5 with: name: module path: tests/srcTestRepo/outputs/module 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@v6 + 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/slim@v8.1.0 + uses: super-linter/super-linter/slim@v8.2.1 env: GITHUB_TOKEN: ${{ github.token }} VALIDATE_MARKDOWN: true 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@v6 + with: + persist-credentials: false + fetch-depth: 0 + + + - name: Action-Test + uses: ./ + with: + Name: PSModuleTest + WorkingDirectory: tests/srcTestRepo + ShowSummaryOnSuccess: true diff --git a/.github/workflows/Auto-Release.yml b/.github/workflows/Auto-Release.yml index a36a9f4..b083552 100644 --- a/.github/workflows/Auto-Release.yml +++ b/.github/workflows/Auto-Release.yml @@ -26,7 +26,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout Code - uses: actions/checkout@v5 + uses: actions/checkout@v6 - name: Auto-Release uses: PSModule/Auto-Release@v1 diff --git a/.github/workflows/Linter.yml b/.github/workflows/Linter.yml index e597aa5..f8f14c6 100644 --- a/.github/workflows/Linter.yml +++ b/.github/workflows/Linter.yml @@ -19,7 +19,7 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout repo - uses: actions/checkout@v5 + uses: actions/checkout@v6 with: persist-credentials: false fetch-depth: 0 diff --git a/README.md b/README.md index 57aea3f..ac76518 100644 --- a/README.md +++ b/README.md @@ -1,47 +1,3 @@ -# Document-PSModule (by PSModule) +# Document-PSModule -A GitHub Action that automates the generation of documentation for PowerShell modules using Markdown help files. - -This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). It is recommended to use the -[Process-PSModule workflow](https://github.com/PSModule/Process-PSModule) to automate the whole process of managing the PowerShell module. - -## Details - -This action: -- Installs necessary modules, including `platyPS` for documentation generation. -- Loads helper scripts required by the documentation process. -- Generates Markdown documentation from PowerShell module files. -- Ensures Markdown documentation is properly formatted, with correctly tagged PowerShell code blocks. -- Adjusts Markdown file paths to mirror the structure of the source PowerShell module files. -- Outputs organized Markdown documentation suitable for publishing or distribution. - -## Usage - -Include this action in your workflow to automatically build and structure documentation for your PowerShell module. - -### Inputs - -| Input | Description | Required | Default | -|--------------------|-----------------------------------------------|----------|-------------| -| `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 - -This action does not require any secrets. - -### Outputs - -This action does not have defined outputs. - -### Example - -```yaml -- name: Document PowerShell Module - uses: PSModule/Document-PSModule@v1 - with: - Name: 'MyModule' - WorkingDirectory: './module-directory' - ShowSummaryOnSuccess: true # Optional: Show summary even on success -``` +This GitHub Action is a part of the [PSModule framework](https://github.com/PSModule). diff --git a/action.yml b/action.yml index 1cd094f..a648223 100644 --- a/action.yml +++ b/action.yml @@ -1,22 +1,19 @@ -name: Document-PSModule (by PSModule) +name: Document-PSModule description: Build documentation for a PowerShell module. author: PSModule -branding: - icon: package - color: gray-dark 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 +24,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 diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index 9ad6e60..e6387c7 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/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 += @" + +
Failed + +

+ +$(($failedCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join '') + +

+ +
+ +"@ + } + + if ($successfulCommands) { + $summaryContent += @" + +
Succeeded -| Command | Status | -|---------|--------| -$(($commandResults | ForEach-Object { "| ``$($_.CommandName)`` | $($_.Status) |`n" }) -join '') +

+ +$(($successfulCommands | ForEach-Object { "- ``$($_.CommandName)`` `n" }) -join '') + +

+ +
"@ + } $summaryContent | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append diff --git a/scripts/main.ps1 b/scripts/main.ps1 index 6557d1c..d9a1d87 100644 --- a/scripts/main.ps1 +++ b/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 diff --git a/tests/srcTestRepo/src/variables/public/Planets.ps1 b/tests/srcTestRepo/src/variables/public/Planets.ps1 index 736584b..5927bc5 100644 --- a/tests/srcTestRepo/src/variables/public/Planets.ps1 +++ b/tests/srcTestRepo/src/variables/public/Planets.ps1 @@ -1,4 +1,4 @@ -$script:Planets = @( +$script:Planets = @( @{ Name = 'Mercury' Mass = 0.330