-
Notifications
You must be signed in to change notification settings - Fork 10
New DscResourcePowerShellHelp
New-DscResourcePowerShellHelp generates PowerShell compatible help files for a DSC resource module.
New-DscResourcePowerShellHelp [-ModulePath] <String> [[-DestinationModulePath] <String>]
[[-OutputPath] <String>] [[-MarkdownCodeRegularExpression] <String[]>] [-Force]
[<CommonParameters>]
Generates conceptual help based on the DSC resources and their examples in a DSC module. This currently only creates English (culture en-US) conceptual help. MOF, class-based and composite resources are supported. Class-based resources must follow the template pattern of the Sampler project. See the project AzureDevOpDsc for an example of the pattern.
After the conceptual help has been created, the user can import the module
and for example run Get-Help about_UserAccountControl to get help about
the DSC resource UserAccountControl.
It is possible to pass a array of regular expressions that should be used to parse the parameter descriptions in the schema MOF. The regular expression must be written so that the capture group 0 is the full match and the capture group 1 is the text that should be kept.
NOTE: This cmdlet does not work on macOS and will throw an error due to the problem discussed in issue https://github.com/PowerShell/PowerShell/issues/5970 and issue https://github.com/PowerShell/MMI/issues/33.
The command will review all of the MOF-based and class-based resources in a specified module directory and will inject PowerShell help files for each resource. These help files include details on the property types for each resource, as well as a text description and examples where they exist.
The help files are output to the OutputPath directory if specified. If not, they are output to the relevant resource's 'en-US' directory either in the path set by 'ModulePath' or to 'DestinationModulePath' if set.
For MOF-based resources a README.md with a text description must exist in the resource's subdirectory for the help file to be generated. For class-based resources each DscResource should have their own file in the Classes folder (using the template of the Sampler project).
To get examples added to the conceptual help the examples must be present in an individual resource example folder, e.g. 'Examples/Resources/MyResourceName/1-Example.ps1'. Prefixing the value with a number will sort the examples in that order.
Example directory structure:
Examples
\---Resources
\---MyResourceName
1-FirstExample.ps1
2-SecondExample.ps1
3-ThirdExample.ps1
These help files can then be read by passing the name of the resource as a parameter to Get-Help.
New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc
This example shows how to generate help for a specific module
New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -DestinationModulePath C:\repos\SharePointDsc\output\SharePointDsc\1.0.0
This example shows how to generate help for a specific module and output the result to a built module.
New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -OutputPath C:\repos\SharePointDsc\en-US
This example shows how to generate help for a specific module and output all the generated files to the same output path.
The destination module path can be used to set the path where module is built before being deployed. This must be set to the root of the built module, e.g 'c:\repos\ModuleName\output\ModuleName\1.0.0'.
The conceptual help file will be saved in this path. For MOF-based resources it will be saved to the 'en-US' folder that is inside in either the 'DSCResources' or 'DSCClassResources' folder (if using that pattern for class-based resources).
When using the pattern with having all powershell classes in the same module script file (.psm1) and all class-based resource are found in that file (not using 'DSCClassResources'). This path will be used to find the built module when generating conceptual help for class-based resource. It will also be used to save the conceptual help to the built modules 'en-US' folder.
If OutputPath is assigned that will be used for saving the output instead.
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseWhen set the to $true and existing conceptual help file will be overwritten.
Type: SwitchParameter
Parameter Sets: (All)
Aliases:
Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: FalseAn array of regular expressions that should be used to parse the text of the synopsis, description and parameter descriptions. Each regular expression must be written so that the capture group 0 is the full match and the capture group 1 is the text that should be kept. This is meant to be used to remove markdown code, but it can be used for anything as it follow the previous mention pattern for the regular expression sequence.
Type: String[]
Parameter Sets: (All)
Aliases:
Required: False
Position: 4
Default value: @()
Accept pipeline input: False
Accept wildcard characters: FalseThe path to the root of the DSC resource module where the PSD1 file is found, for example the folder 'source'. If there are MOF-based resources there should be a 'DSCResources' child folder in this path. If using class-based resources there should be a 'Classes' child folder in this path.
Type: String
Parameter Sets: (All)
Aliases:
Required: True
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThe output path can be used to set the path where all the generated files will be saved (all files to the same path).
Type: String
Parameter Sets: (All)
Aliases:
Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: FalseThis cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Line endings are hard-coded to CRLF to handle different platforms similar.