PlatyPS needs to support the new ProgressAction common parameter

sdwheeler commented 1 year ago

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 commented 10 months ago

As PowerShell 7.4 is officially released, this becomes more urgent

homotechsual commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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

rkphill commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 9 months ago

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 commented 8 months ago

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

sdwheeler commented 8 months ago

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

ArmaanMcleod commented 7 months ago

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 commented 3 months ago

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

techthoughts2 commented 3 months ago

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

sdwheeler commented 3 months ago

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

Alex-wdy commented 3 months ago

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

theJasonHelmick commented 3 months ago

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

Scal-Human commented 2 months ago

Instead of hardcoding strings, the list of common parameters can be retrieved from `

`

PowerShell / platyPS