functions/_Get-ReconciledPSCommandHelp.ps1
|
# <copyright file="_Get-ReconciledPSCommandHelp.ps1" company="Endjin Limited"> # Copyright (c) Endjin Limited. All rights reserved. # </copyright> function _Get-ReconciledPSCommandHelp { <# .SYNOPSIS Builds the set of PlatyPS CommandHelp objects to export for a module. .DESCRIPTION PlatyPS' Update-CommandHelp merges a module's live comment-based help into existing markdown. That merge preserves hand-authored sections that comment-based help can't express (OUTPUTS descriptions, RELATED LINKS, ALIASES) and normalises the file (e.g. the [<CommonParameters>] syntax token) - but it *appends* to the SYNOPSIS, DESCRIPTION, parameter descriptions and example remarks rather than replacing them, so those sections grow a duplicate copy on every build. To get the best of both, every command is put through the same pipeline: a freshly generated markdown file (authoritative, deterministic) is used as the starting point, the existing hand-edited file is layered on top where one exists, Update-CommandHelp merges and normalises, and finally the comment-based-help-derived sections are reset from the freshly generated object to undo the append behaviour. That merge/normalise/reset cycle is repeated until the rendered output stabilises (PlatyPS occasionally needs a second pass, e.g. when a parameter that was missing from the existing file is re-introduced), so a single call produces the final result. .PARAMETER ModuleName The name of the imported module to build CommandHelp objects for. .PARAMETER ExistingDocsPath The folder containing the tracked markdown files to layer hand-authored content from. Pass an empty string when there are no existing docs (e.g. first run). .PARAMETER Locale The locale to pin on the generated CommandHelp objects, so that frontmatter does not vary with the build agent's culture. Optional. .INPUTS None. You can't pipe objects to _Get-ReconciledPSCommandHelp. .OUTPUTS Microsoft.PowerShell.PlatyPS.Model.CommandHelp[]. .EXAMPLE PS:> _Get-ReconciledPSCommandHelp -ModuleName MyModule -ExistingDocsPath ./docs -Locale en-US #> [CmdletBinding()] param( [Parameter(Mandatory)] [string] $ModuleName, [Parameter(Mandatory)] [AllowEmptyString()] [string] $ExistingDocsPath, [Parameter()] [string] $Locale ) $commands = (Get-Module $ModuleName).ExportedCommands.Values | Where-Object CommandType -in 'Function', 'Cmdlet' $freshByTitle = @{} $commands | New-CommandHelp -WarningAction SilentlyContinue | ForEach-Object { $freshByTitle[$_.Title] = $_ } # Stage one markdown file per command. PlatyPS always nests exports under a module-name # sub-folder, so mirror that for the hand-edited files copied in alongside. $workRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("zf-psdocs-stage-" + [Guid]::NewGuid().ToString('N')) $stagePath = Join-Path $workRoot $ModuleName New-Item -ItemType Directory -Path $stagePath -Force | Out-Null $merged = $null try { $freshByTitle.Values | Export-MarkdownCommandHelp -OutputFolder $workRoot -Force | Out-Null # Layer the existing hand-edited files on top of the freshly generated ones. if ($ExistingDocsPath -and (Test-Path $ExistingDocsPath)) { Get-ChildItem -Path (Join-Path $ExistingDocsPath '*.md') | Where-Object { $freshByTitle.ContainsKey([System.IO.Path]::GetFileNameWithoutExtension($_.Name)) } | Copy-Item -Destination $stagePath -Force } $previousRender = $null for ($pass = 1; $pass -le 3; $pass++) { $merged = @(Measure-PlatyPSMarkdown -Path (Join-Path $stagePath '*.md') | Where-Object Filetype -match 'CommandHelp' | Update-CommandHelp -Path { $_.FilePath }) foreach ($commandHelp in $merged) { $fresh = $freshByTitle[$commandHelp.Title] if (!$fresh) { continue } # Reset the sections Update-CommandHelp appends to, from the authoritative source. $commandHelp.Synopsis = $fresh.Synopsis $commandHelp.Description = $fresh.Description # Pin the locale so generated frontmatter doesn't vary with the build agent's culture. if ($Locale) { $commandHelp.Locale = [System.Globalization.CultureInfo]::GetCultureInfo($Locale) if ($commandHelp.Metadata -and $commandHelp.Metadata.Contains('Locale')) { $commandHelp.Metadata['Locale'] = $Locale } } foreach ($parameter in $commandHelp.Parameters) { $freshParameter = $fresh.Parameters | Where-Object Name -eq $parameter.Name | Select-Object -First 1 if ($freshParameter) { $parameter.Description = $freshParameter.Description } } for ($i = 0; $i -lt $commandHelp.Examples.Count -and $i -lt $fresh.Examples.Count; $i++) { $commandHelp.Examples[$i].Remarks = $fresh.Examples[$i].Remarks } } # Re-render and compare (ignoring volatile frontmatter) to see whether another pass # would change anything. Remove-Item -Path (Join-Path $stagePath '*.md') -Force $merged | Export-MarkdownCommandHelp -OutputFolder $workRoot -Force | Out-Null $render = Get-ChildItem -Path (Join-Path $stagePath '*.md') | Sort-Object Name | ForEach-Object { _ConvertTo-NormalisedPSMarkdownContent -Path $_.FullName } | Out-String if ($render -eq $previousRender) { break } $previousRender = $render } } finally { Remove-Item -LiteralPath $workRoot -Recurse -Force -ErrorAction SilentlyContinue } , $merged } |