Private/Generator/ConvertTo-OpenApiGenAbout.ps1
|
function ConvertTo-OpenApiGenAbout { <# .SYNOPSIS Renders the about_<ModuleName> help topic of a generated module (en-US/about_<ModuleName>.help.txt). .DESCRIPTION The short description is the one of the manifest; the long description the document's description (through ConvertTo-OpenApiGenHelpText). COMMANDS lists every command with its summary, SEE ALSO the online help (-HelpUri with {0} = about_<ModuleName>), the document's externalDocs, contact and licence URLs. Text is wrapped at 80 characters; code lines, list items and the command names are kept on one line. #> [CmdletBinding()] [OutputType([string])] param( [Parameter(Mandatory = $true)] [object]$Option, [Parameter(Mandatory = $true)] [object]$Document, [Parameter(Mandatory = $true)] [AllowEmptyCollection()] [object[]]$Function, [Parameter()] [AllowEmptyString()] [string]$ConnectExample = '', [Parameter(Mandatory = $true)] [string]$Template ) $wrap = { param([string]$Text, [int]$Indent) $pad = ' ' * $Indent $width = 80 - $Indent $out = New-Object -TypeName System.Collections.ArrayList $inFence = $false foreach ($line in $Text.Split("`n")) { if ($line -match '^\s*(```|~~~)') { $inFence = -not $inFence [void]$out.Add($pad + $line) continue } if ($inFence -or $line.Trim() -eq '' -or $line.Length -le $width -or $line -match '^\s') { [void]$out.Add(($pad + $line).TrimEnd()) continue } $hanging = '' if ($line -match '^- ') { $hanging = ' ' } $current = '' foreach ($word in ($line -split ' ')) { if ($current -ne '' -and ($current.Length + 1 + $word.Length) -gt $width) { [void]$out.Add($pad + $current) $current = $hanging + $word } elseif ($current -eq '') { $current = $word } else { $current += ' ' + $word } } if ($current -ne '') { [void]$out.Add($pad + $current) } } $out -join "`n" } $isWebUri = { param([string]$Value) $parsed = $null (-not [string]::IsNullOrWhiteSpace($Value)) -and [uri]::TryCreate($Value.Trim(), [System.UriKind]::Absolute, [ref]$parsed) -and @('http', 'https') -contains $parsed.Scheme } $title = ([string]$Document.Title).Trim() if ($title -eq '') { $title = $Option.ModuleName } $short = "PowerShell commands for $title" if (-not [string]::IsNullOrWhiteSpace([string]$Document.Version)) { $short += " (API version $(([string]$Document.Version).Trim()))" } $short += ', generated by tcs.openapi.' $short = ConvertTo-OpenApiGenHelpText -Text $short -SingleLine $long = ConvertTo-OpenApiGenHelpText -Text ([string]$Document.Description) $longText = '' if ($long -ne '') { $longText = (& $wrap $long 4) + "`n" } $commandLines = @() foreach ($item in (Get-OpenApiGenOrdinalSorted -InputObject $Function -Key { [string]$_.Name })) { $commandLines += ' ' + $item.Name $summary = ConvertTo-OpenApiGenHelpText -Text ([string]$item.Summary) -SingleLine if ($summary -ne '') { $commandLines += (& $wrap $summary 8) } } $seeAlso = @() if (-not [string]::IsNullOrWhiteSpace([string]$Option.HelpUri)) { $seeAlso += ([string]$Option.HelpUri).Replace('{0}', "about_$($Option.ModuleName)") } foreach ($url in @($Document.ExternalDocsUrl, $Document.ContactUrl, $Document.LicenseUrl)) { if ((& $isWebUri ([string]$url)) -and $seeAlso -notcontains ([string]$url).Trim()) { $seeAlso += ([string]$url).Trim() } } return Expand-OpenApiGenTemplate -Template $Template -Value @{ ModuleName = $Option.ModuleName Prefix = $Option.Prefix GeneratorVersion = $Option.GeneratorVersion ShortDescription = (& $wrap $short 4) LongDescription = $longText ConnectExample = $ConnectExample CommandList = ($commandLines -join "`n") SeeAlso = (@($seeAlso | ForEach-Object -Process { ' ' + $_ }) -join "`n") } } |