platyPS

platyPS copied to clipboard

Steps to reproduce

Create new markdown help using WithModulePage parameter against a module with platyPS v0.13.0

New-MarkdownHelp -Module slate -WithModulePage -OutputFolder .\docs\

Expected behavior (v.0.12.0)

---
Module Name: slate
Module Guid: 76c6bb29-01fc-4961-bf3c-6e7b6cd11168
Download Help Link: {{Please enter FwLink manually}}
Help Version: {{Please enter version of help manually (X.X.X.X) format}}
Locale: en-US
---

# slate Module
## Description
{{Manually Enter Description Here}}

## slate Cmdlets
### [test-me](test-me.md)
{{Manually Enter test-me Description Here}}

Actual behavior (v.0.13.0)

---
Module Name: slate
Module Guid: 76c6bb29-01fc-4961-bf3c-6e7b6cd11168
Download Help Link: {{ Update Download Link }}
Help Version: {{ Please enter version of help manually (X.X.X.X) format }}
Locale: en-US
---

# slate Module
## Description
{{ Fill in the Description }}

## slate Cmdlets
### [test-me](test-me.md)
{{ Fill in the Description }}

Environment data

Reproduced with:

• PowerShell Core v6.1.3
• Windows PowerShell v5.1
• platyPS v0.13.0

Verbiage change

As you can see from the above, the wording is adjusted when creating a module page with platyPS v.0.13.0.

Thoughts on change

Many of us in the community as part of CI/CD build processes look for these entries and automatically replace them. ex {{Manually Enter Description Here}}

This verbiage change causes that entry lookup effort to fail.

This can of course be addressed by adding logic to account for platyPS v0.12.0 and below, and v0.13.0 and higher. Before going down that route, I wanted to see if there was a reason this change was made. The verbiage change essentially says the same thing, but introduces an element that now has to be accounted for.

This could be adjusted back to the previous verbiage which would prevent issues with upgrading to v.0.13.0. Wanted to hear thoughts on this, and if the verbiage change needed to be made for a reason.

I normalized the messages so it would be consistent between module landing page and cmdlet help files. I picked the cmdlet help file description placeholder since it was used more often.

From your screenshot I do see that the module description and cmdlet description placeholders are the same. May need to fix that so you can replace just the module or specific cmdlet placeholder text.

You can see the list of placeholders here:

https://github.com/PowerShell/platyPS/blob/457b2905f57253a1bef0eefe4c10ebc8cfd0e2ed/src/platyPS/platyPS.Resources.psd1#L61-L71

Sorry for late reply. @techthoughts2 do you have a sense of how common is this pattern in CI? I didn't know it's used in this way.

May need to fix that so you can replace just the module or specific cmdlet placeholder text.

@tnieto88 - I think that's exactly what's needed.

Presently the new version when creating a module page tags the module description and cmldet description placeholders all the same - making it rather difficult to replace them in an automated fashion:

# MyModule 
## Description
{{ Fill in the Description }}

## MyModule Cmdlets
### [Get-AThing](Get-AThing.md)
{{ Fill in the Description }}

### [Get-AThing2](Get-AThing2.md)
{{ Fill in the Description }}

I'm fine with the switch from:

{{Manually Enter Description Here}}

to

{{ Fill in the Description }}

but can we get the cmdlet name included again the cmdlet references?

@vors - I can't speak to the commonality for the community. There are numerous examples online on how to leverage platyPS in a CI/CD deployment in this fashion where the help is created 'on the fly' using string replacements. The recent changes have made that harder and I know of a few folks sticking to v.0.12.0 until this is sorted.

Oh interesting data point!

@techthoughts2 - thank you for raising this issue. We were not aware of this change impacting CI - which you have raised. Apologies for the unknown breaking change for you. We will consider adding the cmdlet name to the placeholder text in a future release.

I worked around this issue with a different regex. Example from my build script. $FunctionsToExport is populated with Import-PowershellDataFile MyModule.psd1

$FunctionsToExport | ForEach-Object {
        Write-Build DarkGray "             Updating definition for the following function: $($_)"
        $Pattern = '(?<=### \[(?<functionName>' + $_ + ')\].*\r?\n)(\{\{ Fill in the Description \}\})'
        $ReplacementText = (Get-Help -Detailed $_).Synopsis
        Write-Build DarkGray $ReplacementText
        $ModulePageFileContent = [regex]::Replace($ModulePageFileContent, $Pattern, $ReplacementText) 
    }

This is totally changing in Microsoft.PowerShell.PlatyPS v1. This no longer applies.