en-US/DscResource.DocGenerator-help.xml
|
<?xml version="1.0" encoding="utf-8"?> <helpItems schema="maml" xmlns="http://msh"> <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>Add-NewLine</command:name> <command:verb>Add</command:verb> <command:noun>NewLine</command:noun> <maml:description> <maml:para>Adds a new line at the end of a file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The Add-NewLineAtEndOfFile function adds a new line at the end of the specified file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Add-NewLine</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>AtEndOfFile</maml:name> <maml:description> <maml:para>Specifies that the new line should be added to the end of the file.</maml:para> </maml:description> <dev:type> <maml:name>SwitchParameter</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>False</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>FileInfo</maml:name> <maml:description> <maml:para>Specifies the file to which the new line will be added.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue> <dev:type> <maml:name>FileInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</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>AtEndOfFile</maml:name> <maml:description> <maml:para>Specifies that the new line should be added to the end of the file.</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="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="named" aliases="none"> <maml:name>FileInfo</maml:name> <maml:description> <maml:para>Specifies the file to which the new line will be added.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue> <dev:type> <maml:name>FileInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes> <command:inputType> <dev:type> <maml:name>[System.IO.FileInfo]</maml:name> </dev:type> <maml:description> <maml:para></maml:para> </maml:description> </command:inputType> <command:inputType> <dev:type> <maml:name>Accepts a FileInfo object representing the file to which the new line will be added.</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. The function does not generate any output.</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 --------------------------</maml:title> <dev:code>Add-NewLineAtEndOfFile -FileInfo "C:\path\to\file.txt" -AtEndOfFile</dev:code> <dev:remarks> <maml:para>Adds a new line at the end of the file located at "C:\path\to\file.txt" without prompting for confirmation.</maml:para> </dev:remarks> </command:example> </command:examples> <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>Edit-CommandDocumentation</command:name> <command:verb>Edit</command:verb> <command:noun>CommandDocumentation</command:noun> <maml:description> <maml:para>Edits the documentation for a command by parsing the comment-based help from the source file.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Edits the documentation for a command by parsing the comment-based help from the source file.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Edit-CommandDocumentation</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Specifies the FileInfo object of the markdown file containing the documentation being edited. This parameter is mandatory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue> <dev:type> <maml:name>FileInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByValue)" position="1" aliases="none"> <maml:name>FilePath</maml:name> <maml:description> <maml:para>Specifies the FileInfo object of the markdown file containing the documentation being edited. This parameter is mandatory.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">FileInfo</command:parameterValue> <dev:type> <maml:name>FileInfo</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>$filePath = Get-Item -Path 'C:\Docs\MyCommand.md' Edit-CommandDocumentation -FilePath $filePath -SourcePath 'C:\Scripts\MyCommand.ps1'</dev:code> <dev:remarks> <maml:para>Edits the documentation for the command specified in the markdown file "C:\Docs\MyCommand.md" using the source file "C:\Scripts\MyCommand.ps1".</maml:para> </dev:remarks> </command:example> </command:examples> <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>Invoke-Git</command:name> <command:verb>Invoke</command:verb> <command:noun>Git</command:noun> <maml:description> <maml:para>Invokes a git command.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Invokes a git command with command line arguments using System.Diagnostics.Process.</maml:para> <maml:para>Throws an error when git ExitCode -ne 0 and -PassThru switch -eq $false (or omitted).</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Invoke-Git</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The path to the git working directory.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>TimeOut</maml:name> <maml:description> <maml:para>Milliseconds to wait for process to exit.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>120000</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Arguments</maml:name> <maml:description> <maml:para>The arguments to pass to the Git executable.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Switch parameter when enabled will return result object of running git command.</maml:para> </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="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>Arguments</maml:name> <maml:description> <maml:para>The arguments to pass to the Git executable.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>PassThru</maml:name> <maml:description> <maml:para>Switch parameter when enabled will return result object of running git command.</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="2" aliases="none"> <maml:name>TimeOut</maml:name> <maml:description> <maml:para>Milliseconds to wait for process to exit.</maml:para> </maml:description> <command:parameterValue required="true" variableLength="false">Int32</command:parameterValue> <dev:type> <maml:name>Int32</maml:name> <maml:uri /> </dev:type> <dev:defaultValue>120000</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>WorkingDirectory</maml:name> <maml:description> <maml:para>The path to the git working directory.</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>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues> <command:returnValue> <dev:type> <maml:name>System.Collections.Hashtable</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 --------------------------</maml:title> <dev:code>Invoke-Git -WorkingDirectory 'C:\SomeDirectory' -Arguments @( 'clone', 'https://github.com/X-Guardian/xActiveDirectory.wiki.git', '--quiet' )</dev:code> <dev:remarks> <maml:para>Invokes the Git executable to clone the specified repository to the working directory.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Invoke-Git -WorkingDirectory 'C:\SomeDirectory' -Arguments @( 'status' ) -TimeOut 10000 -PassThru</dev:code> <dev:remarks> <maml:para>Invokes the Git executable to return the status while having a 10000 millisecond timeout.</maml:para> </dev:remarks> </command:example> </command:examples> <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-DscResourcePowerShellHelp</command:name> <command:verb>New</command:verb> <command:noun>DscResourcePowerShellHelp</command:noun> <maml:description> <maml:para>New-DscResourcePowerShellHelp generates PowerShell compatible help files for a DSC resource module.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>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\ (https://github.com/gaelcolas/Sampler)project. See the project \ AzureDevOpDsc\ (https://github.com/dsccommunity/AzureDevOpsDsc)for an example of the pattern.</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> <maml:para>> 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.</maml:para> <maml:para>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.</maml:para> <maml:para>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.</maml:para> <maml:para>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).</maml:para> <maml:para>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.</maml:para> <maml:para>Example directory structure:</maml:para> <maml:para> Examples \---Resources \---MyResourceName 1-FirstExample.ps1 2-SecondExample.ps1 3-ThirdExample.ps1</maml:para> <maml:para>These help files can then be read by passing the name of the resource as a parameter to Get-Help.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-DscResourcePowerShellHelp</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>ModulePath</maml:name> <maml:description> <maml:para>The 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.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DestinationModulePath</maml:name> <maml:description> <maml:para>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'.</maml:para> <maml:para>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).</maml:para> <maml:para>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.</maml:para> <maml:para>If OutputPath is assigned that will be used for saving the output instead.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>The output path can be used to set the path where all the generated files will be saved (all files to the same path).</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>MarkdownCodeRegularExpression</maml:name> <maml:description> <maml:para>An 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.</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>Force</maml:name> <maml:description> <maml:para>When set the to $true and existing conceptual help file will be overwritten.</maml:para> </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="false" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>DestinationModulePath</maml:name> <maml:description> <maml:para>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'.</maml:para> <maml:para>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).</maml:para> <maml:para>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.</maml:para> <maml:para>If OutputPath is assigned that will be used for saving the output instead.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>When set the to $true and existing conceptual help file will be overwritten.</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="4" aliases="none"> <maml:name>MarkdownCodeRegularExpression</maml:name> <maml:description> <maml:para>An 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.</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>ModulePath</maml:name> <maml:description> <maml:para>The 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.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>The output path can be used to set the path where all the generated files will be saved (all files to the same path).</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>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para>Line endings are hard-coded to CRLF to handle different platforms similar.</maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc</dev:code> <dev:remarks> <maml:para>This example shows how to generate help for a specific module</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -DestinationModulePath C:\repos\SharePointDsc\output\SharePointDsc\1.0.0</dev:code> <dev:remarks> <maml:para>This example shows how to generate help for a specific module and output the result to a built module.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 3 --------------------------</maml:title> <dev:code>New-DscResourcePowerShellHelp -ModulePath C:\repos\SharePointDsc -OutputPath C:\repos\SharePointDsc\en-US</dev:code> <dev:remarks> <maml:para>This example shows how to generate help for a specific module and output all the generated files to the same output path.</maml:para> </dev:remarks> </command:example> </command:examples> <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-DscResourceWikiPage</command:name> <command:verb>New</command:verb> <command:noun>DscResourceWikiPage</command:noun> <maml:description> <maml:para>New-DscResourceWikiPage generates wiki pages that can be uploaded to GitHub to use as public documentation for a module.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>The New-DscResourceWikiPage cmdlet will review all of the MOF-based, class-based and composite resources in a specified module directory and will output the Markdown files to the specified directory. These help files include details on the property types for each resource, as well as a text description and examples where they exist.</maml:para> <maml:para>Generate documentation that can be manually uploaded to the GitHub repository Wiki.</maml:para> <maml:para>It is possible to use markdown code in the schema MOF parameter descriptions. If markdown code is used and conceptual help is also to be generated, configure the task \ \`Generate_Conceptual_Help\`\ (#generate_conceptual_help)to parse the markdown code. See the cmdlet `New-DscResourcePowerShellHelp` and the task \ \`Generate_Conceptual_Help\`\ (#generate_conceptual_help)for more information.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>New-DscResourceWikiPage</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>Where should the files be saved to.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>SourcePath</maml:name> <maml:description> <maml:para>The path to the root of the DSC resource module (where the PSD1 file is found, not the folder for and individual DSC resource).</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>BuiltModulePath</maml:name> <maml:description> <maml:para>The path to the root of the built DSC resource module, e.g. 'output/MyResource/1.0.0'.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites any existing file when outputting the generated content.</maml:para> </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="3" aliases="none"> <maml:name>BuiltModulePath</maml:name> <maml:description> <maml:para>The path to the root of the built DSC resource module, e.g. 'output/MyResource/1.0.0'.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="named" aliases="none"> <maml:name>Force</maml:name> <maml:description> <maml:para>Overwrites any existing file when outputting the generated content.</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="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>OutputPath</maml:name> <maml:description> <maml:para>Where should the files be saved to.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>SourcePath</maml:name> <maml:description> <maml:para>The path to the root of the DSC resource module (where the PSD1 file is found, not the folder for and individual DSC resource).</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>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>New-DscResourceWikiPage ` -SourcePath C:\repos\MyResource\source ` -BuiltModulePath C:\repos\MyResource\output\MyResource\1.0.0 ` -OutputPath C:\repos\MyResource\output\WikiContent</dev:code> <dev:remarks> <maml:para>This example shows how to generate wiki documentation for a specific module.</maml:para> </dev:remarks> </command:example> </command:examples> <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>Publish-WikiContent</command:name> <command:verb>Publish</command:verb> <command:noun>WikiContent</command:noun> <maml:description> <maml:para>Publishes the Wiki Content that is generated by New-DscResourceWikiPage.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Publishes the Wiki content that was generated by the cmdlet `New-DscResourceWikiPage`.</maml:para> <maml:para>If there is an existing `_Sidebar.md` present in the `WikiOutput` folder then it will be published. If there is no existing `_Sidebar.md` in the `WikiOutput` folder a `_Sidebar.md` file will be dynamically generated based on the files in the `WikiOutput` folder.</maml:para> <maml:para>> NOTE: There must already be a Wiki created in the GitHub repository >before using this cmdlet, otherwise it will fail since there is no Wiki >repository.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Publish-WikiContent</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the output that was generated by New-DscResourceWikiPage.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>OwnerName</maml:name> <maml:description> <maml:para>The owner name of the Github repository.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>RepositoryName</maml:name> <maml:description> <maml:para>The name of the Github repository.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ModuleName</maml:name> <maml:description> <maml:para>The name of the Dsc Resource Module.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>ModuleVersion</maml:name> <maml:description> <maml:para>The build version number to tag the Wiki Github commit with.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="6" aliases="none"> <maml:name>GitHubAccessToken</maml:name> <maml:description> <maml:para>The GitHub access token to allow a push to the GitHub Wiki.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="7" aliases="none"> <maml:name>GitUserEmail</maml:name> <maml:description> <maml:para>The email address to use for the Git commit.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="8" aliases="none"> <maml:name>GitUserName</maml:name> <maml:description> <maml:para>The user name to use for the Git commit.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="9" aliases="none"> <maml:name>GlobalCoreAutoCrLf</maml:name> <maml:description> <maml:para>Specifies how line breaks should be handled when cloning the GitHub wiki repository. Valid values are 'true', 'false', or 'input'.</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>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="6" aliases="none"> <maml:name>GitHubAccessToken</maml:name> <maml:description> <maml:para>The GitHub access token to allow a push to the GitHub Wiki.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="7" aliases="none"> <maml:name>GitUserEmail</maml:name> <maml:description> <maml:para>The email address to use for the Git commit.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="8" aliases="none"> <maml:name>GitUserName</maml:name> <maml:description> <maml:para>The user name to use for the Git commit.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="false" variableLength="true" globbing="false" pipelineInput="False" position="9" aliases="none"> <maml:name>GlobalCoreAutoCrLf</maml:name> <maml:description> <maml:para>Specifies how line breaks should be handled when cloning the GitHub wiki repository. Valid values are 'true', 'false', or 'input'.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="4" aliases="none"> <maml:name>ModuleName</maml:name> <maml:description> <maml:para>The name of the Dsc Resource Module.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="5" aliases="none"> <maml:name>ModuleVersion</maml:name> <maml:description> <maml:para>The build version number to tag the Wiki Github commit with.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>OwnerName</maml:name> <maml:description> <maml:para>The owner name of the Github repository.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to the output that was generated by New-DscResourceWikiPage.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="3" aliases="none"> <maml:name>RepositoryName</maml:name> <maml:description> <maml:para>The name of the Github repository.</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>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Publish-WikiContent ` -Path '.\output\WikiContent' ` -OwnerName 'dsccommunity' ` -RepositoryName 'SqlServerDsc' ` -ModuleName 'SqlServerDsc' ` -ModuleVersion '14.0.0' ` -GitHubAccessToken 'token' ` -GitUserEmail 'email@contoso.com' ` -GitUserName 'dsc'</dev:code> <dev:remarks> <maml:para>Adds the content pages in '.\output\WikiContent' to the Wiki for the specified GitHub repository.</maml:para> </dev:remarks> </command:example> <command:example> <maml:title>-------------------------- EXAMPLE 2 --------------------------</maml:title> <dev:code>Publish-WikiContent ` -Path '.\output\WikiContent' ` -OwnerName 'dsccommunity' ` -RepositoryName 'SqlServerDsc' ` -ModuleName 'SqlServerDsc' ` -ModuleVersion '14.0.0' ` -GitHubAccessToken 'token' ` -GitUserEmail 'email@contoso.com' ` -GitUserName 'dsc' ` -GlobalCoreAutoCrLf 'true'</dev:code> <dev:remarks> <maml:para>Adds the content pages in '.\output\WikiContent' to the Wiki for the specified GitHub repository. The wiki repository will be cloned after the git configuration setting `--global core.autocrlf` have been set to `true` making sure the current wiki files are checkout using CRLF.</maml:para> </dev:remarks> </command:example> </command:examples> <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>Set-WikiModuleVersion</command:name> <command:verb>Set</command:verb> <command:noun>WikiModuleVersion</command:noun> <maml:description> <maml:para>Changes all placeholders (#.#.#) in a markdown file to the specified module version.</maml:para> </maml:description> </command:details> <maml:description> <maml:para>Changes all placeholders (#.#.#) in a markdown file to the specified module version.</maml:para> </maml:description> <command:syntax> <command:syntaxItem> <maml:name>Set-WikiModuleVersion</maml:name> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to a markdown file to set the module version in.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ModuleVersion</maml:name> <maml:description> <maml:para>The base name of the Wiki Sidebar file. Defaults to '_Sidebar.md'.</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>None</dev:defaultValue> </command:parameter> </command:syntaxItem> </command:syntax> <command:parameters> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="2" aliases="none"> <maml:name>ModuleVersion</maml:name> <maml:description> <maml:para>The base name of the Wiki Sidebar file. Defaults to '_Sidebar.md'.</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>None</dev:defaultValue> </command:parameter> <command:parameter required="true" variableLength="true" globbing="false" pipelineInput="False" position="1" aliases="none"> <maml:name>Path</maml:name> <maml:description> <maml:para>The path to a markdown file to set the module version in.</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>None</dev:defaultValue> </command:parameter> </command:parameters> <command:inputTypes /> <command:returnValues /> <maml:alertSet> <maml:alert> <maml:para></maml:para> </maml:alert> </maml:alertSet> <command:examples> <command:example> <maml:title>-------------------------- EXAMPLE 1 --------------------------</maml:title> <dev:code>Set-WikiModuleVersion -Path '.\output\WikiContent\Home.md' -ModuleVersion '14.0.0'</dev:code> <dev:remarks> <maml:para>Replaces '#.#.#' with the module version '14.0.0' in the markdown file 'Home.md'.</maml:para> </dev:remarks> </command:example> </command:examples> <command:relatedLinks /> </command:command> </helpItems> |