PlatyPS needs to support the new ProgressAction common parameter

Question

PlatyPS needs to support the new ProgressAction common parameter

sdwheeler opened this issue 2 years ago · 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

Answer 1 · 2023-11-17T12:26:22.000Z

As PowerShell 7.4 is officially released, this becomes more urgent

Answer 2 · 2023-11-19T04:43:30.000Z

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?

Answer 3 · 2023-11-20T14:21:49.000Z

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.

Answer 4 · 2023-11-20T14:28:14.000Z

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.

Answer 5 · 2023-11-21T13:55:13.000Z

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

Answer 6 · 2023-11-27T15:41:44.000Z

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

Answer 7 · 2023-11-27T16:32:11.000Z

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

Answer 8 · 2023-11-28T09:51:34.000Z

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

Answer 9 · 2023-11-28T09:53:15.000Z

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

Answer 10 · 2023-12-08T16:21:51.000Z

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

Answer 11 · 2023-12-11T19:48:10.000Z

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
}

Answer 12 · 2023-12-11T21:09:54.000Z

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

Answer 13 · 2023-12-25T08:02:05.000Z

https://github.com/PowerShell/platyPS

Are there any updates planned for platyPS ?

Answer 14 · 2023-12-26T14:37:09.000Z

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

Answer 15 · 2024-02-05T10:44:18.000Z

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.

Answer 16 · 2024-05-17T20:15:56.000Z

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

Answer 17 · 2024-05-18T03:40:15.000Z

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

Answer 18 · 2024-05-18T13:24:02.000Z

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

Answer 19 · 2024-05-24T00:54:13.000Z

@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?

Answer 20 · 2024-05-24T15:21:29.000Z

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