PlatyPS needs to support the new ProgressAction common parameter

[sdwheeler]

Prerequisites

• [X] Write a descriptive title.
• [X] Make sure you are able to repro it on the latest released version
• [X] 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

[peetrike]

As PowerShell 7.4 is officially released, this becomes more urgent

[homotechsual]

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?

[sdwheeler]

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.

[homotechsual]

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.

[homotechsual]

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)
    }
}

[rkphill]

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

[sdwheeler]

The ProgressAction parameter only shows up in the output when you run PlatyPS on PowerShell 7.4.

[rkphill]

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

[homotechsual]

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

[PleaseStopAsking]

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

[SVHawk13]

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
}

[homotechsual]

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 :-)

[Alex-wdy]

https://github.com/PowerShell/platyPS
Are there any updates planned for platyPS ?

[sdwheeler]

@Alex-wdy Yes. We are actively working on a complete rewrite. No ETA yet.

[ArmaanMcleod]

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.

[theJasonHelmick]

This is included in the Microsoft.PowerShell.PlatyPS 1.0 release.

[techthoughts2]

@theJasonHelmick - can you clarify a bit further? Where can one access the Microsoft.PowerShell.PlatyPS 1.0 release?

[sdwheeler]

@techthoughts2 For now, this is a private internal release. We make an announcement when it is available. It will be published to the Gallery.