2

I've been trying to improve our PS documentation and started playing with PlatyPS. So far, it's been great, I have nice markdown docs now. I'm also able to generate MAML for use with CLI documentation from it and have been able to remove the doc-comment strings from my modules.

Unfortunately, when I import my module it's unable to see the MAML help files and Get-Help for my exported function is very barebones.

My understanding is that when packaging MAML within a module, they need to be placed as follows:

MyModuleName/
  |_ en-US/
     |_ MyModuleName-help.xml

However, I have done this, but I am still unable to see the proper help documentation from the command line with Get-Help or -?. This is my first foray into using external help documentation that doesn't use doc-comments, so I'm hoping I'm missing a step or making a MAML beginner's mistake.

codewario
  • 19,553
  • 20
  • 90
  • 159

1 Answers1

0

As it turns out, I was hitting a problem when generating the MAML from the markdown source. I was following this guide to PlatyPS and New-ExternalHelp was not generating help for the commands I happened to be testing with.

These commands were not named with the Verb-Noun nomenclature, and the files shared a name with their matching function. I took one of the functions and gave it a Verb-Noun name instead and did the same with its corresponding .md file. With a pattern of Verb-Noun.md, New-ExternalHelp now generated the command's MAML and placed them inside of MyModuleName-help.xml.

However, this is not what I wanted. These particular functions are named like commands on purpose, and I do not want to follow the Verb-Noun nomenclature for them. An edge case, probably, but I did find a solution for this as well. After a bit of testing, only the command name in the source .md file for that command matters as far as MAML generation.

The filename needs to match the Verb-Noun.md pattern, but you can have the command called FunctionName inside and the help will generate correctly for the command FunctionName, not Verb-Noun. Now when I import the module, I get the correct help topic for the commands that were previously missing.

Now my .md file no longer matches the command name but that isn't the end of the world.

codewario
  • 19,553
  • 20
  • 90
  • 159