PlatyPS: PowerShell Help meets Markdown by Sergei Vorobev
4PlatyPS: PowerShell Help meets Markdown by Sergei Vorobev
PlatyPS solves a long standing pain of writing PowerShell external help xmls. Now you can write help in markdown and verify that it reflects the code. PlatyPS brings modern markdown-based workflows to the PowerShell help authoring. We will take a deep dive in the PowerShell help engine and platyPS.
PlatyPS solves a long standing pain of writing PowerShell external help xmls.It provides a way to
* Write PowerShell External Help in Markdown
* Generate markdown help for your existing modules
* Keep markdown help up-to-date with your code
* Generate help artifacts (maml xmls and online help archives) from markdown and ship them with your modules
Traditionally PowerShell external help files have been authored by hand or using complex tool chains and rendered as MAML XML for use as console help.
MAML is cumbersome to edit by hand, and common tools and editors don't provide good support for working with it.
Markdown is a very easy markup language which became a standard for writing documentation.
We will take a look at existing big projects that are using it (like Azure and PowerShell-Docs) and some smaller projects (like PSReadLine). We will go through a (very easy!) bootstrap process for using platyPS in an existing project. We will also cover how to make sure that documentation is up to date and even add tests to your CI pipeline to make sure that documentation is always updated.
In the second part of the talk, we will take a deep dive into platyPS internals. We will talk about markdown schema, quirks of PowerShell help engine and tool limitations. We will also cover advanced topics, like combining few different versions of your module help into a single markdown document.
Every part of the talk will be accompanied by hands on live demos.