PlatyPS needs to support the new ProgressAction common parameter #595

sdwheeler · 2023-03-23T17:59:38Z

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

The text was updated successfully, but these errors were encountered:

peetrike · 2023-11-17T12:26:22Z

As PowerShell 7.4 is officially released, this becomes more urgent

homotechsual · 2023-11-19T04:43:30Z

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 · 2023-11-20T14:21:49Z

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 · 2023-11-20T14:28:14Z

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 · 2023-11-21T13:55:13Z

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 · 2023-11-27T15:41:44Z

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 · 2023-11-27T16:32:11Z

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

rkphill · 2023-11-28T09:51:34Z

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 · 2023-11-28T09:53:15Z

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 · 2023-12-08T16:21:51Z

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 · 2023-12-11T19:48:10Z

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 · 2023-12-11T21:09:54Z

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 · 2023-12-25T08:02:05Z

https://github.com/PowerShell/platyPS

Are there any updates planned for platyPS ?

sdwheeler · 2023-12-26T14:37:09Z

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

ArmaanMcleod · 2024-02-05T10:44:18Z

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.

- Add devcontainer and codespaces support - Fix platyps bug, see PowerShell/platyPS#595 - Update function .md files - Update issue templates - Update first .LINK in all CBH to repo url update devcontainer.json update devcontainer.json update comments in bootstrap.ps1 Fix platyps bug, see PowerShell/platyPS#595 test codespaces Update first .LINK in all CBH to repo url Update .md files update readme.md Update readme and add new issue template

This time PowerShell/platyPS#595 hopefully this is the last one for a while... 😬

theJasonHelmick · 2024-05-17T20:15:56Z

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

techthoughts2 · 2024-05-18T03:40:15Z

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

sdwheeler · 2024-05-18T13:24:02Z

@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 · 2024-05-24T00:54:13Z

@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 · 2024-05-24T15:21:29Z

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

sdwheeler added the Needs-Triage The issue is new and needs to be triaged by a work group. label Mar 23, 2023

sdwheeler added this to the OPS-Release milestone Nov 7, 2023

homotechsual mentioned this issue Nov 19, 2023

Fix common parameters for PowerShell 7.4.0. #611

Open

PalmEmanuel mentioned this issue Dec 16, 2023

platyPS generates markdown documentation for parameter new common parameter -ProgressAction in PowerShell 7.4 PalmEmanuel/AzAuth#38

Closed

wyunchi-ms mentioned this issue Dec 22, 2023

Ping the PowerShell task version in code-gen to 2.232.1 Azure/azure-powershell#23816

Merged

6 tasks

techthoughts2 mentioned this issue Jan 16, 2024

CreateMarkdownHelp step in build process failing in PowerShell 7.4.0+ techthoughts2/Catesta#71

Closed

connorcarnes added a commit to connorcarnes/pwshCloudflare that referenced this issue Feb 13, 2024

Fix platyps bug, see PowerShell/platyPS#595

b4ad217

connorcarnes added a commit to connorcarnes/pwshCloudflare that referenced this issue Feb 13, 2024

Fix platyps bug, see PowerShell/platyPS#595

c7172f6

connorcarnes mentioned this issue Feb 13, 2024

Updates to devenv and docs connorcarnes/pwshCloudflare#15

Merged

wyunchi-ms mentioned this issue Feb 22, 2024

Remove the ProgressAction in help files Azure/azure-powershell#24210

Merged

6 tasks

SeeminglyScience mentioned this issue Apr 8, 2024

.md files generated with PlatyPS incorrectly include -ProgressAction parameter section. PowerShell/PowerShell#21445

Closed

5 tasks

shoddyguard added a commit to Brownserve-UK/Brownserve.PSTools that referenced this issue Apr 13, 2024

feat: add cmdlets to work around even more PlatyPS issues.

7cfe5ec

This time PowerShell/platyPS#595 hopefully this is the last one for a while... 😬

theJasonHelmick closed this as completed May 17, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

PlatyPS needs to support the new ProgressAction common parameter #595

PlatyPS needs to support the new ProgressAction common parameter #595

sdwheeler commented Mar 23, 2023

peetrike commented Nov 17, 2023 •

edited

homotechsual commented Nov 19, 2023

sdwheeler commented Nov 20, 2023

homotechsual commented Nov 20, 2023

homotechsual commented Nov 21, 2023 •

edited

rkphill commented Nov 27, 2023

sdwheeler commented Nov 27, 2023

rkphill commented Nov 28, 2023

homotechsual commented Nov 28, 2023

PleaseStopAsking commented Dec 8, 2023

SVHawk13 commented Dec 11, 2023 •

edited

homotechsual commented Dec 11, 2023

Alex-wdy commented Dec 25, 2023

sdwheeler commented Dec 26, 2023

ArmaanMcleod commented Feb 5, 2024

theJasonHelmick commented May 17, 2024

techthoughts2 commented May 18, 2024

sdwheeler commented May 18, 2024

Alex-wdy commented May 24, 2024

theJasonHelmick commented May 24, 2024

PlatyPS needs to support the new ProgressAction common parameter #595

PlatyPS needs to support the new ProgressAction common parameter #595

Comments

sdwheeler commented Mar 23, 2023

Prerequisites

Steps to reproduce

Expected behavior

Actual behavior

Error details

Environment data

Visuals

peetrike commented Nov 17, 2023 • edited

homotechsual commented Nov 19, 2023

sdwheeler commented Nov 20, 2023

homotechsual commented Nov 20, 2023

homotechsual commented Nov 21, 2023 • edited

rkphill commented Nov 27, 2023

sdwheeler commented Nov 27, 2023

rkphill commented Nov 28, 2023

homotechsual commented Nov 28, 2023

PleaseStopAsking commented Dec 8, 2023

SVHawk13 commented Dec 11, 2023 • edited

homotechsual commented Dec 11, 2023

Alex-wdy commented Dec 25, 2023

sdwheeler commented Dec 26, 2023

ArmaanMcleod commented Feb 5, 2024

theJasonHelmick commented May 17, 2024

techthoughts2 commented May 18, 2024

sdwheeler commented May 18, 2024

Alex-wdy commented May 24, 2024

theJasonHelmick commented May 24, 2024

peetrike commented Nov 17, 2023 •

edited

homotechsual commented Nov 21, 2023 •

edited

SVHawk13 commented Dec 11, 2023 •

edited