platyPS
platyPS copied to clipboard
PowerShell
Update-MarkdownHelpModule should not require dashes in all cmdlet names
I've following code:
New-MarkdownHelp -Module $Module -OutputFolder $PSScriptRoot\..\docs
Update-MarkdownHelp $PSScriptRoot\..\docs
New-ExternalHelp $PSScriptRoot\..\docs -OutputPath $PSScriptRoot\..\docs -Force
I run it to update docs, but also create new word docs when I add new functions. I get errors (as the files exists)
I don't want to use -Force as I guess the file will be overwritten and any changes to it as well. Yet I need an option to create new docs as I add more functions.
I don't quite follow the scenario you have. Are you using one of the common setups?
It sounds like you run New-MarkdownHelp in CI, which suggests that source of truth is not in markdown. But then why would you run New-ExternalHelp?
@vors Interesting find... Update-MarkdownHelpModule and I was using Update-MarkdownHelp. What is the difference and why there are 2? :-)
And the other problem is, while it did found new file, created it. But then I rerun and I get an error. Only on that new file that was just created (and not on the rest that are untouched).
What is the difference and why there are 2? :-)
One is for HelpModules which are folders of docs with a index markdown doc with some metadata that's needed to create .cab files and such. In this example it talks exactly about your use-case https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md#example-1-update-a-markdown-help-module
Right... but sti.ll
Gets me this:
It's funny thou because it recognized all other files and skipped them properly. It creted Testing.md when I run it the first time but subsequent try results in this errror.
This one is quite weird. I've created all those commands...
Rerun the tool once, it creates all files:
It creates them. When you rerun the tool it only fails on the ones that have no "-" in it.
After tracking it down it is related to:
function GetMarkdownFilesFromPath
{
[CmdletBinding()]
param(
[Parameter(Mandatory=$true)]
[SupportsWildcards()]
[string[]]$Path,
[switch]$IncludeModulePage
)
if ($IncludeModulePage)
{
$filter = '*.md'
}
else
{
$filter = '*-*.md'
}
...
You explicitly assume - is required for non-module page.
This can be fixed in couple of ways I guess but since I don't know whole product...
- It seems it's not used anywhere with the switch so maybe switch could be removed
- Filter for IncludeModulePage can be updated to something different - to what is a bit hard to guess for now
- Any other?
Oh, I see so it's the naming convention really - we should not assume that everything without a - is a module page for the module update scenario.
As a workaround for now you can use Update-MarkdownHelp and pass the list of commands to it explicitly, since it doesn't have this limitation about the dash.
Do you have "best" way to go forward with a fix? I mean I don't use this command lately so I don't need it but seeing as I already found a case I may as well fix it. Just not sure what would be your approach (unless there's bigger issue here...)
Perhaps we can use Get-YamlMetadata to check keys that are common in the module page vs cmdlet markdown and use that instead of the file name for the heuristic.
New-ExternalHelp has this exact same issue since it also calls GetMarkdownFilesFromPath. As a result, when I run New-ExternalHelp on my module (consisting solely of one word functions without dashes) I get absolutely no output.
Is there any workaround one can implement in that scenario to generate the external XML file?
@lordmilko it's a matter of tweaking GetMarkdownFilesFromPath. If you want to take a stab at it, perhaps you can simply avoid filtering there for the Verb-Noun pattern and add a new switch parameter -RelaxCmdletNameCheck or something.
Adding a new switch should be simple enough, but the question is whether it's a good idea. Discoverability of this new switch wouldn't be really straight forward.
And if you notice there's already switch that enables/disables this behavior IncludeModulePage that when used would solve the issue.
This should already be fixed in Microsoft.PowerShell.PlatyPS v1. The workflow is going to be different in the new release, so even if there is a problem, a new issue should be opened against the new version once it is released.
