PlatyPS needs to support the new ProgressAction common parameter

[sdwheeler]

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

[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