en-US/platyPS.psm1-Help.xml

<?xml version="1.0" encoding="utf-8"?>
<helpItems schema="maml">
 
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>Get-PlatyPSExternalHelp</command:name>
<command:verb>Get</command:verb>
<command:noun>PlatyPSExternalHelp</command:noun>
<maml:description><maml:para>Create External help file from platyPS markdown.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>Create External help file from platyPS markdown.
</maml:para>
<maml:para>You will get error messages, if provided input doesn't follow schema described in platyPS.schema.md
</maml:para>
<maml:para>Store output of this command in the module directory in corresponding language folder, i.e en-US.
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>Get-PlatyPSExternalHelp</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>MarkdownFolder</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>skipPreambula</maml:name>
<maml:Description></maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
<command:syntaxItem><maml:name>Get-PlatyPSExternalHelp</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>markdown</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string[]</command:parameterValue>
<dev:type><maml:name>string[]</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>skipPreambula</maml:name>
<maml:Description></maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>MarkdownFolder</maml:name>
<maml:Description><maml:para>Path to a folder with "*.md" files. Their content would be extracted and used. It may be convinient for big modules. Also breaking markdown to several files speed-up convertion process.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>markdown</maml:name>
<maml:Description><maml:para>This parameter takes array of string, so you can simply pipe output of Get-Content .
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string[]</command:parameterValue>
<dev:type><maml:name>string[]</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>skipPreambula</maml:name>
<maml:Description><maml:para>Switch to avoid emmiting xml preambula and &lt;helpitems&gt; tag.
</maml:para>
</maml:Description>
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes></command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>System.String</maml:name>
</dev:type>
<maml:description><maml:para>Xml document that should be stored to the module folder in the corresponding language folder.
</maml:para>
<maml:para>I.e. en-US\platyPS.psm1-Help.xml
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>----------------------------- Example 1 (platyPS) ------------------------------------</maml:title>
<dev:code>$maml = Get-PlatyPSExternalHelp -markdown (cat -raw .\src\platyPS\platyPS.md)
mkdir out\platyPS\en-US -ErrorAction SilentlyContinue &gt; $null
Set-Content -path out\platyPS\en-US\platyPS.psm1-Help.xml -Value $maml -Encoding UTF8</dev:code>
<dev:remarks><maml:para>
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 2 (skipPreambula) ------------------------------------</maml:title>
<dev:code>$markdown = Get-PlatyPSMarkdown Get-PlatyPSMarkdown | Out-String
Get-PlatyPSExternalHelp -markdown $markdown -skipPreambula | clip</dev:code>
<dev:remarks><maml:para>Create $maml entry for one command and copy it to clip-board to copy-paste it into existing maml.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 3 (MarkdownFolder) ------------------------------------</maml:title>
<dev:code>$maml = Get-PlatyPSExternalHelp -MarkdownFolder .\src\platyPS</dev:code>
<dev:remarks><maml:para>You can break help for the big module into several markdown files and put them into a folder. In this case, you may find -MarkdownFolder parameter more convinient.
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks><maml:navigationLink><maml:linkText>PowerShell V2 External MAML Help</maml:linkText>
<maml:uri>https://blogs.msdn.microsoft.com/powershell/2008/12/24/powershell-v2-external-maml-help/</maml:uri>
</maml:navigationLink>
</command:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>Get-PlatyPSMarkdown</command:name>
<command:verb>Get</command:verb>
<command:noun>PlatyPSMarkdown</command:noun>
<maml:description><maml:para>Convert your existing external help into markdown or generate it from Help object.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>An easy way to start with platyPS: Generate help stub from:
</maml:para>
<maml:para>- Module.
</maml:para>
<maml:para>- Command.
</maml:para>
<maml:para>- External help xml (aka maml).
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>Get-PlatyPSMarkdown</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>command</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
<dev:type><maml:name>Object</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OneFilePerCommand</maml:name>
<maml:Description></maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OutputFolder</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:syntaxItem>
<command:syntaxItem><maml:name>Get-PlatyPSMarkdown</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>maml</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OneFilePerCommand</maml:name>
<maml:Description></maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OutputFolder</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:syntaxItem>
<command:syntaxItem><maml:name>Get-PlatyPSMarkdown</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>module</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
<dev:type><maml:name>Object</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OneFilePerCommand</maml:name>
<maml:Description></maml:Description>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OutputFolder</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>command</maml:name>
<maml:Description><maml:para>Name of a command from your PowerShell session.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
<dev:type><maml:name>Object</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>maml</maml:name>
<maml:Description><maml:para>Path or content of file with existing External Help (aka maml).
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"><maml:name>module</maml:name>
<maml:Description><maml:para>Name of the module for bulk help generation.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">Object</command:parameterValue>
<dev:type><maml:name>Object</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OneFilePerCommand</maml:name>
<maml:Description><maml:para>Use this switch to create a folder with one .md file per cmdlet. This parameter requires specifing -OutputFolder.
</maml:para>
</maml:Description>
<command:parameterValue required="false" variableLength="false">SwitchParameter</command:parameterValue>
<dev:type><maml:name>SwitchParameter</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue>False</dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="named" aliases="none"><maml:name>OutputFolder</maml:name>
<maml:Description><maml:para>Path to a folder to output markdown files. This parameter requires -OneFilePerCommand.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes><command:inputType><dev:type><maml:name>System.Object</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
<command:inputType><dev:type><maml:name>System.String</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>System.String[]</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>----------------------------- Example 1 (from command) ------------------------------------</maml:title>
<dev:code>function foo {param([string]$bar)}
Get-PlatyPSMarkdown -command foo</dev:code>
<dev:remarks><maml:para>Create stub markdown on the fly from the function foo.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 2 (from module) ------------------------------------</maml:title>
<dev:code>Import-Module platyPS
Get-PlatyPSMarkdown -module platyPS</dev:code>
<dev:remarks><maml:para>Module should be loaded in the PS Session.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 3 (from maml file path) ------------------------------------</maml:title>
<dev:code>Get-PlatyPSMarkdown -maml 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml'</dev:code>
<dev:remarks><maml:para>Create markdown help for inbox PSReadLine module.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 4 (from maml file content) ------------------------------------</maml:title>
<dev:code>Get-PlatyPSMarkdown -maml (cat -raw 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml')</dev:code>
<dev:remarks><maml:para>Create markdown help for inbox PSReadLine module.
</maml:para>
</dev:remarks>
</command:example>
<command:example><maml:title>----------------------------- Example 4 (maml, OneFilePerCommand) ------------------------------------</maml:title>
<dev:code>Get-PlatyPSMarkdown -maml 'C:\Program Files\WindowsPowerShell\Modules\PSReadline\1.1\en-US\Microsoft.PowerShell.PSReadline.dll-help.xml' -OneFilePerCommand -OutputFolder PSReadLineHelp</dev:code>
<dev:remarks><maml:para>Create markdown help for inbox PSReadLine module and output them into a PSReadLineHelp folder. Create one .md file per cmdlet.
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks></command:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>New-PlatyPSModuleFromMaml</command:name>
<command:verb>New</command:verb>
<command:noun>PlatyPSModuleFromMaml</command:noun>
<maml:description><maml:para>Takes a MAML file and generates a script module with corresponding help at the given location.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>Command generates dummy module with particular External Help file. You can use it to see, how generated help will look like.
</maml:para>
<maml:para>This cmdlet generates an object which contains the module name, module path and the list of cmdlets for the generated module.
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>New-PlatyPSModuleFromMaml</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>DestinationPath</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters><command:parameter required="false" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>DestinationPath</maml:name>
<maml:Description><maml:para>Path to a folder, where module should be generated.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name>
<maml:Description><maml:para>Path to the External Help file.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>System.Object</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>----------------------------- Example 1 (test the module) ------------------------------------</maml:title>
<dev:code>$generatedModule = New-PlatyPSModuleFromMaml -MamlFilePath $outMamlFilePath
$generatedModule.Cmdlets | % { Get-Help -Name "$($generatedModule.Name)\$_" -Full | Out-String }</dev:code>
<dev:remarks><maml:para>Show generated help for the whole module as an output of Help engine system.
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks></command:relatedLinks>
</command:command>
<command:command xmlns:maml="http://schemas.microsoft.com/maml/2004/10" xmlns:command="http://schemas.microsoft.com/maml/dev/command/2004/10" xmlns:dev="http://schemas.microsoft.com/maml/dev/2004/10" xmlns:MSHelp="http://msdn.microsoft.com/mshelp">
<command:details><command:name>Get-PlatyPSTextHelpFromMaml</command:name>
<command:verb>Get</command:verb>
<command:noun>PlatyPSTextHelpFromMaml</command:noun>
<maml:description><maml:para>Get help text from an external help file xml as a plain text file.
</maml:para>
</maml:description>
</command:details>
<maml:description><maml:para>Command cretes a temp module with specified external help file and queries help engine to produce a text help for it.
</maml:para>
</maml:description>
<command:syntax><command:syntaxItem><maml:name>Get-PlatyPSTextHelpFromMaml</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>TextOutputPath</maml:name>
<maml:Description></maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters><command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="0" aliases="none"><maml:name>MamlFilePath</maml:name>
<maml:Description><maml:para>Path to the External Help file.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="false" position="1" aliases="none"><maml:name>TextOutputPath</maml:name>
<maml:Description><maml:para>Path to output file with generated text help.
</maml:para>
</maml:Description>
<command:parameterValue required="true" variableLength="false">string</command:parameterValue>
<dev:type><maml:name>string</maml:name>
<maml:uri /></dev:type>
<dev:defaultValue></dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes><command:inputType><dev:type><maml:name>None</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:inputType>
</command:inputTypes>
<command:returnValues><command:returnValue><dev:type><maml:name>None</maml:name>
</dev:type>
<maml:description><maml:para>
</maml:para>
</maml:description>
</command:returnValue>
</command:returnValues>
<maml:alertSet><maml:alert><maml:para>
</maml:para>
</maml:alert>
</maml:alertSet>
<command:examples><command:example><maml:title>----------------------------- Example 1 (platyPS) ------------------------------------</maml:title>
<dev:code>Get-PlatyPSTextHelpFromMaml .\out\platyPS\en-US\platyPS.psm1-Help.xml -TextOutputPath platyPS.txt</dev:code>
<dev:remarks><maml:para>
</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks></command:relatedLinks>
</command:command>
</helpItems>