🩹 [Patch]: Update to use Microsoft.PowerShell.PlatyPS for docs generation (#19)

## Description

This pull request introduces several improvements to the documentation
generation process, CI workflows, and PowerShell module metadata. The
most significant changes include enhanced and more robust documentation
generation, updates to GitHub Actions workflows for better security and
linting, and improvements to module help comments for consistency.

**Documentation generation improvements:**

* The `Build-PSModuleDocumentation.ps1` script now generates markdown
help per command, handles documentation file organization to match
source structure, and fixes frontmatter titles for compatibility. This
makes the documentation process more robust and the output more
consistent.
[[1]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L50-R75)
[[2]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L91-R148)
* The script now uses the full module name
`Microsoft.PowerShell.PlatyPS` for installation, ensuring compatibility.

**GitHub Actions workflow enhancements:**

* The `Action-Test.yml` workflow now requests explicit permissions for
reading contents and writing statuses, uses a full-depth fetch for
checkouts, logs file changes, commits documentation updates, and adds a
markdown linter step.
[[1]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4L18-R20)
[[2]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4R29-R31)
[[3]](diffhunk://#diff-a12ae5c885b0673c0ff6f70c2670886907590d624626e07da4c52e01aeaf56a4R46-R63)
* The `Linter.yml` workflow disables certain linters for performance and
disables credential persistence for increased security.
[[1]](diffhunk://#diff-482e65806ed9e4a7320f14964764086b91fed4a28d12e4efde1776472e147e79R24)
[[2]](diffhunk://#diff-482e65806ed9e4a7320f14964764086b91fed4a28d12e4efde1776472e147e79R34-R35)

**PowerShell module metadata improvements:**

* Added `.DESCRIPTION` sections to all module functions for better help
output, and added `.NOTES` with control instructions to
`Set-PSModuleTest` and its corresponding public function.
[[1]](diffhunk://#diff-b6253bdc18cdabe21d009dc3778e7ef0d84effe3d28242d670a938b0f710920cR259-R261)
[[2]](diffhunk://#diff-b6253bdc18cdabe21d009dc3778e7ef0d84effe3d28242d670a938b0f710920cR288-R290)
[[3]](diffhunk://#diff-b6253bdc18cdabe21d009dc3778e7ef0d84effe3d28242d670a938b0f710920cR319-R331)
[[4]](diffhunk://#diff-b6253bdc18cdabe21d009dc3778e7ef0d84effe3d28242d670a938b0f710920cR356-R358)
[[5]](diffhunk://#diff-1d4bb1ca6780e5c612c9b2db51bb1c07c381ef6608cd52a7780ec786ad6946cdR10-R15)

Link:
https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.platyps/new-markdowncommandhelp?view=ps-modules

Author: MariusStorhaug

.github/workflows/Action-Test.yml

@@ -15,7 +15,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
-permissions: {}
+permissions:
+  contents: read # to checkout the repo
+  statuses: write # to create commit status
 
 jobs:
   ActionTestDefault:
@@ -24,6 +26,9 @@ jobs:
     steps:
       - name: Checkout repo
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+          fetch-depth: 0
 
       - name: Upload module artifact
         uses: actions/upload-artifact@v4
@@ -38,3 +43,21 @@ jobs:
         with:
           Name: PSModuleTest
           WorkingDirectory: tests/srcTestRepo
+
+      - name: Get changes
+        uses: PSModule/GitHub-Script@v1
+        with:
+          Script: |
+            LogGroup "List files" {
+              Get-ChildItem -Recurse -File | Select-Object -ExpandProperty FullName | Sort-Object
+            }
+            LogGroup "Commit changes" {
+              git add tests/srcTestRepo/outputs/docs/
+              git commit -m "Update documentation"
+            }
+
+      - name: Lint documentation
+        uses: super-linter/super-linter/slim@7bba2eeb89d01dc9bfd93c497477a57e72c83240 # v8.2.0
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+          VALIDATE_MARKDOWN: true

.github/workflows/Linter.yml

@@ -21,6 +21,7 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v5
         with:
+          persist-credentials: false
           fetch-depth: 0
 
       - name: Lint code base
@@ -30,3 +31,5 @@ jobs:
           VALIDATE_JSON_PRETTIER: false
           VALIDATE_MARKDOWN_PRETTIER: false
           VALIDATE_YAML_PRETTIER: false
+          VALIDATE_BIOME_FORMAT: false
+          VALIDATE_GITHUB_ACTIONS_ZIZMOR: false

scripts/helpers/Build-PSModuleDocumentation.ps1

@@ -47,8 +47,32 @@
 
     Write-Host '::group::Build docs - Generate markdown help - Raw'
     Install-PSModule -Path $ModuleOutputFolder
-    Write-Host ($ModuleName | Get-Module)
-    $null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
+    $moduleInfo = Import-Module -Name $ModuleName -Force -PassThru
+
+    # Get all exported commands from the module
+    $commands = $moduleInfo.ExportedCommands.Values | Where-Object { $_.CommandType -ne 'Alias' }
+
+    Write-Host "Found $($commands.Count) commands to process"
+
+    foreach ($command in $commands) {
+        try {
+            Write-Host "$($command.Name)" -NoNewline
+            $params = @{
+                CommandInfo    = $command
+                OutputFolder   = $docsOutputFolder
+                Encoding       = 'utf8'
+                ProgressAction = 'SilentlyContinue'
+                ErrorAction    = 'Stop'
+                Force          = $true
+            }
+            $null = New-MarkdownCommandHelp @params
+            Write-Host ' - ✓' -ForegroundColor Green
+        } catch {
+            Write-Host ' - ✗' -ForegroundColor Red
+            $_
+        }
+    }
+
     Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $fileName = $_.Name
         Write-Host "::group:: - [$fileName]"
@@ -88,30 +112,40 @@
 
     Write-Host '::group::Build docs - Structure markdown files to match source files'
     $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
-    Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+    $moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName
+    Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $file = $_
-        $relPath = [System.IO.Path]::GetRelativePath($DocsOutputFolder.FullName, $file.FullName)
+        $relPath = [System.IO.Path]::GetRelativePath($moduleDocsFolder, $file.FullName)
         Write-Host " - $relPath"
         Write-Host "   Path:     $file"
 
         # find the source code file that matches the markdown file
         $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
         Write-Host "   PS1 path: $scriptPath"
-        $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
+        $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder).Replace('.ps1', '.md')
         Write-Host "   MD path:  $docsFilePath"
         $docsFolderPath = Split-Path -Path $docsFilePath -Parent
         $null = New-Item -Path $docsFolderPath -ItemType Directory -Force
         Move-Item -Path $file.FullName -Destination $docsFilePath -Force
     }
 
+    Write-Host '::group::Build docs - Fix frontmatter title'
+    Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
+        $content = Get-Content -Path $_.FullName -Raw
+        # Replace 'title:' with 'ms.title:' in frontmatter only (between --- markers)
+        $content = $content -replace '(?s)^(---.*?)title:(.*?---)', '$1ms.title:$2'
+        $content | Set-Content -Path $_.FullName
+    }
+
     Write-Host '::group::Build docs - Move markdown files from source files to docs'
+    $moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName
     Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
         $file = $_
         $relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName)
         Write-Host " - $relPath"
         Write-Host "   Path:     $file"
 
-        $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
+        $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder)
         Write-Host "   MD path:  $docsFilePath"
         $docsFolderPath = Split-Path -Path $docsFilePath -Parent
         $null = New-Item -Path $docsFolderPath -ItemType Directory -Force

scripts/main.ps1

@@ -7,7 +7,7 @@ param()
 
 $PSStyle.OutputRendering = 'Ansi'
 
-'platyPS' | ForEach-Object {
+'Microsoft.PowerShell.PlatyPS' | ForEach-Object {
     $name = $_
     Write-Output "Installing module: $name"
     $retryCount = 5

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

@@ -256,6 +256,9 @@ function Get-PSModuleTest {
         .SYNOPSIS
         Performs tests on a module.
 
+        .DESCRIPTION
+        Performs tests on a module.
+
         .EXAMPLE
         Test-PSModule -Name 'World'
 
@@ -282,6 +285,9 @@ function New-PSModuleTest {
         .SYNOPSIS
         Performs tests on a module.
 
+        .DESCRIPTION
+        Performs tests on a module.
+
         .EXAMPLE
         Test-PSModule -Name 'World'
 
@@ -310,10 +316,19 @@ function Set-PSModuleTest {
         .SYNOPSIS
         Performs tests on a module.
 
+        .DESCRIPTION
+        Performs tests on a module.
+
         .EXAMPLE
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .NOTES
+        Controls:
+        - :q      : Quit
+        - :q!     : Quit without saving
+        - :wq     : Save and quit
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',
@@ -338,6 +353,9 @@ function Test-PSModuleTest {
         .SYNOPSIS
         Performs tests on a module.
 
+        .DESCRIPTION
+        Performs tests on a module.
+
         .EXAMPLE
         Test-PSModule -Name 'World'
 

tests/srcTestRepo/src/functions/public/SomethingElse/Set-PSModuleTest.ps1

@@ -7,6 +7,12 @@
         Test-PSModule -Name 'World'
 
         "Hello, World!"
+
+        .NOTES
+        Controls:
+        - :q      : Quit
+        - :q!     : Quit without saving
+        - :wq     : Save and quit
     #>
     [Diagnostics.CodeAnalysis.SuppressMessageAttribute(
         'PSUseShouldProcessForStateChangingFunctions', '', Scope = 'Function',