PlatyPS needs to support the new ProgressAction common parameter
sdwheeler opened this issue · 21 comments
Prerequisites
- Write a descriptive title.
- Make sure you are able to repro it on the latest released version
- Search the existing issues.
Steps to reproduce
PowerShell 7.4 added a new Common Parameter, -ProgressAction
.
When you run New-MarkdownHelp
on 7.4, it adds an ### -ProgressAction
parameter section to the markdown. Also, -ProgressAction
is not listed with the rest of the parameters in the ### CommonParameters
section.
Expected behavior
Treat `-ProgressAction` as a CommonParameter
Actual behavior
see above
Error details
No response
Environment data
PowerShell 7.4.0-preview.2
PlatyPS 0.14.2
Visuals
No response
As PowerShell 7.4 is officially released, this becomes more urgent
Because this parameter has no description being a common parameter and PlatyPS uses {{ }}
to wrap placeholders this breaks MDX v2 / v3 rendering. Is there anything we can do to get this over the line quicker?
We are in the process of a near-complete rewrite. This will be addressed in the next version.
For now, remove the ### -ProgressAction
section from the markdown. It is not supposed to be listed as a normal parameter. It is covered by the ## CommonParameters
section.
We are in the process of a near-complete rewrite. This will be addressed in the next version.
For now, remove the
### -ProgressAction
section from the markdown. It is not supposed to be listed as a normal parameter. It is covered by the## CommonParameters
section.
The issue is that it's not covered by the common parameters section currently - which is a statically defined list of the common parameters - so when automatically generating the markdown we're getting an extra section which is missing a parameter description (because it's a common parameter) AND it's missing from the list of common parameters.
For the benefit of others this can remove any parameter block from the PlatyPS markdown file by name.
function WriteFile() {
<#
.SYNOPSIS
Writes content to a UTF-8 file without BOM using LF as newlines.
#>
param(
[Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile,
[Parameter(Mandatory = $True)]$Content
)
# replace file (UTF-8 without BOM)
$fileEncoding = New-Object System.Text.UTF8Encoding $False
# when content is a string
if (($Content.GetType().Name -eq "String")) {
[System.IO.File]::WriteAllText($MarkdownFile.FullName, $Content, $fileEncoding)
return
}
# when content is an array
[System.IO.File]::WriteAllLines($MarkdownFile.FullName, $Content, $fileEncoding)
}
function RemoveParameter() {
<#
.SYNOPSIS
Remove a PlatyPS generated parameter block.
.DESCRIPTION
Removes parameter block for the provided parameter name from the markdown file provided.
#>
[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute("PSReviewUnusedParameter", "NoPlaceHolderExamples",
Justification = 'False positive as rule does not scan child scopes')]
param(
[Parameter(Mandatory = $True)][System.IO.FileSystemInfo]$MarkdownFile,
[Parameter(Mandatory = $True)][String]$ParameterName
)
$content = ReadFile -MarkdownFile $MarkdownFile -Raw
if (-not($ParameterName.StartsWith('-'))) {
$ParameterName = ('-{0}' -f $ParameterName)
}
# $break = [System.Environment]::NewLine * 2
# extract the parameter block identified by the given variable
# https://regex101.com/r/YlpGva
$pattern = "### $ParameterName\r?\n[\S\s\r\n]*?(?=#{2,3}?)"
$regex = [regex]::new($Pattern, [System.Text.RegularExpressions.RegexOptions]::Multiline)
$parameters = $regex.Matches($content)
if ($parameters.Count -gt 0) {
# process the parameter
Write-Verbose ('Removing parameter {0} from {1}' -f $ParameterName, $MarkdownFile.BaseName)
$content = [regex]::replace($content, $pattern, '')
# replace file
WriteFile -MarkdownFile $MarkdownFile -Content $content
} else {
Write-Verbose ('No parameter nodes matching {0} found in {1}' -f $ParameterName, $MarkdownFile.BaseName)
}
}
We are in the process of a near-complete rewrite. This will be addressed in the next version.
For now, remove the
### -ProgressAction
section from the markdown. It is not supposed to be listed as a normal parameter. It is covered by the## CommonParameters
section.
IS there a way not to do this each time? And is this going to be a complete rewrite in that all bugfixes are halted for the next x years? Ground up rewrites seem a great way to kill project momentum
The ProgressAction parameter only shows up in the output when you run PlatyPS on PowerShell 7.4.
The ProgressAction parameter only shows up in the output when you run PlatyPS on PowerShell 7.4.
Thanks, that's what I'm doing, I'd like it to not do that
The ProgressAction parameter only shows up in the output when you run PlatyPS on PowerShell 7.4.
Thanks, that's what I'm doing, I'd like it to not do that
As it stands right now your only options are to post-process it out (using something like the functions I posted above), to remove it manually or to ensure your docs generation happens on PowerShell 7.3.10 instead of 7.4.0
As a temporary fix, we implemented the below snippet into our build process until this is addressed via an official release. This simply adds ProgressAction
to the array in the psm1 file. Its hacky but works
if ($env:BHBuildSystem -ieq 'GitHub Actions') { $PlatyPSPath = '/home/runner/.local/share/powershell/Modules/platyPS/0.14.2/platyPS.psm1' } else { $PlatyPSPath = '/root/.local/share/powershell/Modules/platyPS/0.14.2/platyPS.psm1' }
$FileContent = Get-Content -Path $PlatyPSPath
$FileContent[2544] = "{0}`r`n{1}" -f "'ProgressAction',", $FileContent[2544]
$FileContent | Set-Content $PlatyPSPath
The below functions can be used to properly update your Markdown with -ProgressAction.
- Remove-CommonParameterFromMarkdown removes any given common parameter(s) from your PlatyPS Markdown file, including within a function's syntax.
- Add-MissingCommonParameterToMarkdown adds any given parameter(s) to the list of common parameters in your PlatyPS Markdown.
- Repair-PlatyPSMarkdown wraps both Remove-CommonParameterFromMarkdown and Add-MissingCommonParameterToMarkdown to conveniently run both.
# modified from source: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702
function Remove-CommonParameterFromMarkdown {
<#
.SYNOPSIS
Remove a PlatyPS generated parameter block.
.DESCRIPTION
Removes parameter block for the provided parameter name from the markdown file provided.
#>
param(
[Parameter(Mandatory)]
[string[]]
$Path,
[Parameter(Mandatory = $false)]
[string[]]
$ParameterName = @('ProgressAction')
)
$ErrorActionPreference = 'Stop'
foreach ($p in $Path) {
$content = (Get-Content -Path $p -Raw).TrimEnd()
$updateFile = $false
foreach ($param in $ParameterName) {
if (-not ($Param.StartsWith('-'))) {
$param = "-$($param)"
}
# Remove the parameter block
$pattern = "(?m)^### $param\r?\n[\S\s]*?(?=#{2,3}?)"
$newContent = $content -replace $pattern, ''
# Remove the parameter from the syntax block
$pattern = " \[$param\s?.*?]"
$newContent = $newContent -replace $pattern, ''
if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) {
Write-Verbose "Added $param to $p"
# Update file content
$content = $newContent
$updateFile = $true
}
}
# Save file if content has changed
if ($updateFile) {
$newContent | Out-File -Encoding utf8 -FilePath $p
Write-Verbose "Updated file: $p"
}
}
return
}
function Add-MissingCommonParameterToMarkdown {
param(
[Parameter(Mandatory)]
[string[]]
$Path,
[Parameter(Mandatory = $false)]
[string[]]
$ParameterName = @('ProgressAction')
)
$ErrorActionPreference = 'Stop'
foreach ($p in $Path) {
$content = (Get-Content -Path $p -Raw).TrimEnd()
$updateFile = $false
foreach ($NewParameter in $ParameterName) {
if (-not ($NewParameter.StartsWith('-'))) {
$NewParameter = "-$($NewParameter)"
}
$pattern = '(?m)^This cmdlet supports the common parameters:(.+?)\.'
$replacement = {
$Params = $_.Groups[1].Captures[0].ToString() -split ' '
$CommonParameters = @()
foreach ($CommonParameter in $Params) {
if ($CommonParameter.StartsWith('-')) {
if ($CommonParameter.EndsWith(',')) {
$CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length -1)
} elseif ($p.EndsWith('.')) {
$CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length -1)
} else{
$CleanParam = $CommonParameter
}
$CommonParameters += $CleanParam
}
}
if ($NewParameter -notin $CommonParameters) {
$CommonParameters += $NewParameter
}
$CommonParameters = ($CommonParameters | Sort-Object)
$CommonParameters[-1] = "and $($CommonParameters[-1])."
return "This cmdlet supports the common parameters: " + (($CommonParameters) -join ', ')
}
$newContent = $content -replace $pattern, $replacement
if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) {
Write-Verbose "Added $NewParameter to $p"
$updateFile = $true
$content = $newContent
}
}
# Save file if content has changed
if ($updateFile) {
$newContent | Out-File -Encoding utf8 -FilePath $p
Write-Verbose "Updated file: $p"
}
}
return
}
function Repair-PlatyPSMarkdown {
param(
[Parameter(Mandatory)]
[string[]]
$Path,
[Parameter()]
[string[]]
$ParameterName = @('ProgressAction')
)
$ErrorActionPreference = 'Stop'
$Parameters = @{
Path = $Path
ParameterName = $ParameterName
}
$null = Remove-CommonParameterFromMarkdown @Parameters
$null = Add-MissingCommonParameterToMarkdown @Parameters
return
}
The below functions can be used to properly update your Markdown with -ProgressAction.
- Remove-CommonParameterFromMarkdown removes any given common parameter(s) from your PlatyPS Markdown file, including within a function's syntax.
- Add-MissingCommonParameterToMarkdown adds any given parameter(s) to the list of common parameters in your PlatyPS Markdown.
- Repair-PlatyPSMarkdown wraps both Remove-CommonParameterFromMarkdown and Add-MissingCommonParameterToMarkdown to conveniently run both.
# modified from source: https://github.com/PowerShell/platyPS/issues/595#issuecomment-1820971702 function Remove-CommonParameterFromMarkdown { <# .SYNOPSIS Remove a PlatyPS generated parameter block. .DESCRIPTION Removes parameter block for the provided parameter name from the markdown file provided. #> param( [Parameter(Mandatory)] [string[]] $Path, [Parameter(Mandatory = $false)] [string[]] $ParameterName = @('ProgressAction') ) $ErrorActionPreference = 'Stop' foreach ($p in $Path) { $content = (Get-Content -Path $p -Raw).TrimEnd() $updateFile = $false foreach ($param in $ParameterName) { if (-not ($Param.StartsWith('-'))) { $param = "-$($param)" } # Remove the parameter block $pattern = "(?m)^### $param\r?\n[\S\s]*?(?=#{2,3}?)" $newContent = $content -replace $pattern, '' # Remove the parameter from the syntax block $pattern = " \[$param\s?.*?]" $newContent = $newContent -replace $pattern, '' if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { Write-Verbose "Added $param to $p" # Update file content $content = $newContent $updateFile = $true } } # Save file if content has changed if ($updateFile) { $newContent | Out-File -Encoding utf8 -FilePath $p Write-Verbose "Updated file: $p" } } return } function Add-MissingCommonParameterToMarkdown { param( [Parameter(Mandatory)] [string[]] $Path, [Parameter(Mandatory = $false)] [string[]] $ParameterName = @('ProgressAction') ) $ErrorActionPreference = 'Stop' foreach ($p in $Path) { $content = (Get-Content -Path $p -Raw).TrimEnd() $updateFile = $false foreach ($NewParameter in $ParameterName) { if (-not ($NewParameter.StartsWith('-'))) { $NewParameter = "-$($NewParameter)" } $pattern = '(?m)^This cmdlet supports the common parameters:(.+?)\.' $replacement = { $Params = $_.Groups[1].Captures[0].ToString() -split ' ' $CommonParameters = @() foreach ($CommonParameter in $Params) { if ($CommonParameter.StartsWith('-')) { if ($CommonParameter.EndsWith(',')) { $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length -1) } elseif ($p.EndsWith('.')) { $CleanParam = $CommonParameter.Substring(0, $CommonParameter.Length -1) } else{ $CleanParam = $CommonParameter } $CommonParameters += $CleanParam } } if ($NewParameter -notin $CommonParameters) { $CommonParameters += $NewParameter } $CommonParameters[-1] = "and $($CommonParameters[-1]). " return "This cmdlet supports the common parameters: " + (($CommonParameters | Sort-Object) -join ', ') } $newContent = $content -replace $pattern, $replacement if ($null -ne (Compare-Object -ReferenceObject $content -DifferenceObject $newContent)) { Write-Verbose "Added $NewParameter to $p" $updateFile = $true $content = $newContent } } # Save file if content has changed if ($updateFile) { $newContent | Out-File -Encoding utf8 -FilePath $p Write-Verbose "Updated file: $p" } } return } function Repair-PlatyPSMarkdown { param( [Parameter(Mandatory)] [string[]] $Path, [Parameter()] [string[]] $ParameterName = @('ProgressAction') ) $ErrorActionPreference = 'Stop' $Parameters = @{ Path = $Path ParameterName = $ParameterName } $null = Remove-CommonParameterFromMarkdown @Parameters $null = Add-MissingCommonParameterToMarkdown @Parameters return }
Nice, very nice :-)
https://github.com/PowerShell/platyPS
Are there any updates planned for platyPS ?
It's quite unbelievable this is not fixed yet and forcing the community to come up with ridiculous workarounds. Makes no sense to not to accept a fix in the meantime while the rewrite is happening with no ETA.
This is included in the Microsoft.PowerShell.PlatyPS 1.0 release.
@theJasonHelmick - can you clarify a bit further? Where can one access the Microsoft.PowerShell.PlatyPS 1.0
release?
@techthoughts2 For now, this is a private internal release. We make an announcement when it is available. It will be published to the Gallery.
@techthoughts2 For now, this is a private internal release. We make an announcement when it is available. It will be published to the Gallery.
Can I get this private package for early testing? If so, where can I get it?
Hi @techthoughts2 and @Alex-wdy -- Thank you for your interest in PlatyPS! This new version is still a work in progress that is going through testing. Once we have stabilized and met our quality bar, we will look to release as a public build. We appreciate your enthusiasm and patience while we finish :)