🩹 [Patch]: Update to use Microsoft.PowerShell.PlatyPS for docs generation

.github/workflows/Action-Test.yml

@@ -15,7 +15,9 @@
   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 @@
     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 @@
         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',