Edit

New-ExternalHelp

  • Reference
Module:
platyPS

Creates external help file based on markdown supported by PlatyPS.

Syntax

New-ExternalHelp
   -Path <String[]>
   -OutputPath <String>
   [-ApplicableTag <String[]>]
   [-Encoding <Encoding>]
   [-MaxAboutWidth <Int32>]
   [-ErrorLogFile <String>]
   [-Force]
   [-ShowProgress]
   [<CommonParameters>]

Description

The New-ExternalHelp cmdlet creates an external help file based on markdown help files supported by PlatyPS. You can ship this with a module to provide help using the Get-Help cmdlet.

If the markdown files that you specify don't follow the PlatyPS Schema, this cmdlet returns error messages.

Examples

Example 1: Create external help based on the contents of a folder

PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US"

    Directory: D:\Working\PlatyPS\out\platyPS\en-US


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/19/2016  12:32 PM          46776 platyPS-help.xml

This command creates an external help file in the specified location. This command uses the best practice that the folder name includes the locale.

Example 2: Create help that uses custom encoding

PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\PlatyPS\en-US" -Force -Encoding ([System.Text.Encoding]::Unicode)


    Directory: D:\Working\PlatyPS\out\PlatyPS\en-US


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/22/2016   6:34 PM         132942 platyPS-help.xml

This command creates an external help file in the specified location. This command specifies the Force parameter, therefore, it overwrites an existing file. The command specifies Unicode encoding for the created file.

Example 3: Write warnings and errors to file

PS C:\> New-ExternalHelp -Path ".\docs" -OutputPath "out\platyPS\en-US" -ErrorLogFile ".\WarningsAndErrors.json"

    Directory: D:\Working\PlatyPS\out\platyPS\en-US


Mode                LastWriteTime         Length Name
----                -------------         ------ ----
-a----        5/19/2016  12:32 PM          46776 platyPS-help.xml

This command creates an external help file in the specified location. This command uses the best practice that the folder name includes the locale. This command writes the warnings and errors to the WarningsAndErrors.json file.

Parameters

-ApplicableTag

Specify array of tags to use as a filter. If cmdlet has applicable in the yaml metadata and none of the passed tags is mentioned there, cmdlet would be ignored in the generated help. Same applies to the Parameter level applicable yaml metadata. If applicable is omitted, cmdlet or parameter would be always present. See design issue for more details.

Type:String[]
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Encoding

Specifies the character encoding for your external help file. Specify a System.Text.Encoding object. For more information, see about_Character_Encoding.

Type:Encoding
Position:Named
Default value:UTF8 without BOM
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-ErrorLogFile

The path where this cmdlet will save formatted results log file.

The path must include the location and name of the folder and file name with the json extension. The JSON object contains three properties: Message, FilePath, and Severity (Warning or Error).

If this path isn't provided, no log is generated.

Type:String
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-Force

Indicates that this cmdlet overwrites an existing file that has the same name.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-MaxAboutWidth

Specifies the maximum line length when generating "about" help text files. Other help file types are not affected by this parameter. For more information, see New-MarkdownAboutHelp.

Lines inside code blocks aren't wrapped and aren't affected by the MaxAboutWidth parameter.

Type:Int32
Position:Named
Default value:80
Required:False
Accept pipeline input:False
Accept wildcard characters:False

-OutputPath

Specifies the path of a folder where this cmdlet saves your external help file. The folder name should end with a locale folder, as in the following example: .\out\PlatyPS\en-US\.

Type:String
Position:Named
Default value:None
Required:True
Accept pipeline input:False
Accept wildcard characters:False

-Path

Specifies an array of paths of markdown files or folders. This cmdlet creates external help based on these files and folders.

Type:String[]
Position:Named
Default value:None
Required:True
Accept pipeline input:True
Accept wildcard characters:True

-ShowProgress

Display progress bars under parsing existing markdown files.

If this is used generating of help is much slower.

Type:SwitchParameter
Position:Named
Default value:None
Required:False
Accept pipeline input:False
Accept wildcard characters:False

Inputs

String[]

You can pipe an array of paths to this cmdlet.

Outputs

FileInfo[]

This cmdlet returns a FileInfo[] object for created files.