Getting Started with PlatyPS

platyps.md

Getting started with PlatyPS

• Start by importing most recent version of module
• I try to fill in as much information as possible in my parameter attributes before creating my innitial markdown. Having all of these filled out helps when using PlatyPS in place of comment based help. PlatyPS still has a few issues with some attributes when using Update-MarkdownHelp try to fill in all attribute like the following.
  • [SupportsWildcards()]
  • [PSDefaultValue(Help='whatever the default value is')]
  • [OutputType([if there is an outputtype])]
  • [CmdletBinding()]
  • [Alias()]
  • DefaultParameterSetName=""
  • SupportsShouldProcess
  • All Paremeter attributes like HelpMessage
• Now you run New-MarkdownHelp -Module $Module -OutputPath .\docs I actually use .\docs\Commands since I use PlatyPS with ReadTheDocs and I have my index.md in the docs root and subfolders for topics.
• This gives you your Markdown and I would first go through and just check everything ported over properly. It wants your examples to be sort of formatted with your command as the very first line, so you may have to adjust the examples slightly.
• Another thing to check is your Related Links sort of section. There have been some changes in this area and currently all items require a valid url.
• Once you have the markdown updated, you can use New-ExternalHelp .\docs -OutputPath en-US\ or New-ExternalHelp .\docs\Commands -OutputPath en-US\ if you use the Commands folder.
• When you update the code in your module, say you add some new commands, import the latest module Import-Module $Module -Force and then run Update-MarkdownHelp -Path .\docs or Update-MarkdownHelp -Path .\docs\Commands and it should update any changes from your module.

Workflow should looks something like this

# Get started by importing latest module version
Import-Module $Module -Force
New-MarkdownHelp -Module $Module -OutputPath .\docs

# Check formatting and make any changes then create the External xml
New-ExternalHelp .\docs -OutputPath en-US\

# After making changes to the module, Update the Markdown help
Import-Module $Module -Force
Update-MarkdownHelp -Path .\docs

Thanks for this! I'll be testing it out shortly. I use MkDocs for documentation but manually generating docs for my function reference is silly and I don't want to do it anymore.