How do I format and name the examples in my PowerShell script documentation?

Question

I would like to apply the same style of documentation for script examples to my scripts that is frequently demonstrated in the native documentation. As an example, consider the help for the Invoke-Command command.

Get-Help Invoke-Command -Examples

The output of this command contains the following:

Example 3: Run a command in a persistent connection

PS C:\>$s = New-PSSession -ComputerName Server02 -Credential Domain01\User01
PS C:\> Invoke-Command -Session $s -ScriptBlock {Get-Culture}

How do I name my examples so that they appear as above instead of the default -------------------------- EXAMPLE 3 -------------------------- header? The latter is rendered when using a .EXAMPLE directive in the documentation tag.

Furthermore, how can I leverage multi-line examples so that they include the shell path prefix (PS C:\?). I can manually enter this prefix in my documentation to create the effect but I was wondering if there is a different and more compliant method.

Patrick Meinecke · Accepted Answer · 2017-08-15 01:02:00Z

The way to do this is with an external help MAML XML file. Either created by hand, or by utilizing the PlatyPS module to create MAML from markdown. You can also use PlatyPS to create markdown from comment based help (CBH).

Using PlatyPS:

# Create markdown from CBH in a module
New-MarkdownHelp -Module MyModule -OutputFolder .\docs -Locale en-US

# Create MAML external help, usually in a build step
New-ExternalHelp -Path .\docs -OutputPath .\moduleOutFolder\en-US

# Then you can optionally replace the CBH with a link to the external help
# file so you only need to adjust the markdown

<#
.EXTERNALHELP MyModuleName-help.xml
#>

When creating the initial markdown, you will probably have to manually adjust the markdown for multi line examples. For this reason and a few other preference differences I usually only maintain the markdown and replace the CBH.

Collectives™ on Stack Overflow

How do I format and name the examples in my PowerShell script documentation?

1 Answer 1

Comments

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Related