Merge pull request Azure#3104 from cormacpayne/update-platyps-help

Update documentation for platyPSHelp

Author: markcowl

documentation/platyps-help.md

@@ -30,7 +30,7 @@ If your service does not currently have any markdown help, follow the below step
 
 ### Installing the `platyPSHelp` Module
 
-The `platyPSHelp` module contains cmdlets that will help service teams with creating, updating, and validating markdown help. 
+The `platyPSHelp` module contains cmdlets that will help service teams with creating, updating, and validating markdown help for their cmdlets.
 
 There are three cmdlets contained in this module:
 - `New-ServiceMarkdownHelp`
@@ -61,15 +61,15 @@ There are four possible parameter sets to choose from when creating your cmdlets
 - `FullPath`
     - This parameter set will be used if there is an issue when using any of the above parameter sets (*e.g.*, the path to the XML help (MAML) or commands folder does not follow what the cmdlet is expecting); in this case, you can provide the full path to the required items
 
-More information about this cmdlet can be found in the [help]("..\tools\platyPSHelp\help\New-ServiceMarkdownHelp.md").
+More information about this cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/New-ServiceMarkdownHelp.md).
 
 Once ran, this cmdlet will create markdown files for each of the cmdlets in your module, and will be placed in the help folder located on the same level as your XML help (MAML). It will also regenerate the XML help (MAML) to ensure that the information in the markdown help is seen when `Get-Help` or `Get-HelpPreview` is ran.
 
 ### Running the `Validate-ServiceMarkdownHelp` cmdlet
 
 Before checking in this markdown, you will need to check to make sure all of the necessary parts are filled out (*i.e.*, synopsis, description, examples, parameter descriptions, and outputs). 
 
-This cmdlet contains the same four parameter sets as the `New-ServiceMarkdownHelp`, and more information about the cmdlet can be found in the [help]("..\tools\platyPSHelp\help\Validate-ServiceMarkdownHelp.md").
+This cmdlet contains the same four parameter sets as the `New-ServiceMarkdownHelp`, and more information about the cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Validate-ServiceMarkdownHelp.md).
 
 Once ran, this cmdlet will output a list of errors for each cmdlet in the following format:
 
@@ -91,7 +91,7 @@ This will let you know what parts of the markdown help need to be updated. A rec
 
 Anytime that you make changes to a cmdlet (*e.g.*, add/edit/remove parameter, edit output type, etc.), you will need to make sure that those changes are reflected in the markdown. The `Update-ServiceMarkdownHelp` cmdlet will update your markdown with the changes made to your cmdlets.
 
-This cmdlet contains the same four parameter sets as the other two cmdlets, and more information about the cmdlet can be found in the [help]("..\tools\platyPSHelp\help\Update-ServiceMarkdownHelp.md").
+This cmdlet contains the same four parameter sets as the other two cmdlets, and more information about the cmdlet can be found in the [help](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Update-ServiceMarkdownHelp.md).
 
 In addition to updating the markdown help files, it will also regenerate the XML help (MAML) to ensure that the information in the markdown help is seen when `Get-Help` or `Get-HelpPreview` is ran.
 

tools/platyPSHelp/help/New-ServiceMarkdownHelp.md

@@ -13,25 +13,22 @@ This cmdlet will create markdown help files for each cmdlet in a given service,
 
 ### ServiceManagement
 ```
-New-ServiceMarkdownHelp -Service <String> -BuildTarget <String> -PathToRepo <String> [-ServiceManagement]
- [<CommonParameters>]
+New-ServiceMarkdownHelp -Service <String> -BuildTarget <String> [-ServiceManagement] [<CommonParameters>]
 ```
 
 ### ResourceManager
 ```
-New-ServiceMarkdownHelp -Service <String> -BuildTarget <String> -PathToRepo <String> [-ResourceManager]
- [<CommonParameters>]
+New-ServiceMarkdownHelp -Service <String> -BuildTarget <String> [-ResourceManager] [<CommonParameters>]
 ```
 
 ### Storage
 ```
-New-ServiceMarkdownHelp -BuildTarget <String> -PathToRepo <String> [-Storage] [<CommonParameters>]
+New-ServiceMarkdownHelp -BuildTarget <String> [-Storage] [<CommonParameters>]
 ```
 
 ### FullPath
 ```
-New-ServiceMarkdownHelp -PathToModule <String> -PathToCommandsFolder <String> -ModuleName <String>
- [<CommonParameters>]
+New-ServiceMarkdownHelp -PathToModule <String> -PathToCommandsFolder <String> [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -47,28 +44,27 @@ To ensure that the generated markdown help files have all of the necessary field
 
 ### -------------------------- Example 1: Creating markdown for an ARM service --------------------------
 ```
-PS C:\> New-ServiceMarkdownHelp -Service Profile -BuildTarget Debug -PathToRepo C:\azure-powershell -ResourceManager
+PS C:\> New-ServiceMarkdownHelp -Service Profile -BuildTarget Debug -ResourceManager
 ```
 
-This example will create markdown help files for all of the Profile cmdlets. It will import the Profile module from C:\azure-powershell\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.Profile\AzureRM.Profile.psd1 and create a help folder in C:\azure-powershell\src\ResourceManager\Profile\Commands.Profile.
+This example will create markdown help files for all of the Profile cmdlets. It will import the Profile module from PATH_TO_REPO\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.Profile\AzureRM.Profile.psd1 and create a help folder in PATH_TO_REPO\src\ResourceManager\Profile\Commands.Profile.
 
-It will also regenerate the existing XML help (MAML) located at C:\azure-powershell\src\ResourceManager\Profile\Commands.Profile\Microsoft.Azure.Commands.Profile.dll-Help.xml.
+It will also regenerate the existing XML help (MAML) located at PATH_TO_REPO\src\ResourceManager\Profile\Commands.Profile\Microsoft.Azure.Commands.Profile.dll-Help.xml.
 
 ### -------------------------- Example 2: Creating markdown for Storage --------------------------
 ```
-PS C:\> New-ServiceMarkdownHelp -BuildTarget Debug -PathToRepo C:\azure-powershell -Storage
+PS C:\> New-ServiceMarkdownHelp -BuildTarget Debug -Storage
 ```
 
-This example will create markdown help files for all of the Storage cmdlets. It will import the Storage module from C:\azure-powershell\src\Package\Debug\Storage\Azure.Storage\Azure.Storage.psd1 and create a help folder in C:\azure-powershell\src\Storage\Commands.Storage.
+This example will create markdown help files for all of the Storage cmdlets. It will import the Storage module from PATH_TO_REPO\src\Package\Debug\Storage\Azure.Storage\Azure.Storage.psd1 and create a help folder in PATH_TO_REPO\src\Storage\Commands.Storage.
 
-It will also regenerate the existing XML help (MAML) located at C:\azure-powershell\src\Storage\Commands.Storage\Microsoft.WindowsAzure.Commands.Storage.dll-Help.xml.
+It will also regenerate the existing XML help (MAML) located at PATH_TO_REPO\src\Storage\Commands.Storage\Microsoft.WindowsAzure.Commands.Storage.dll-Help.xml.
 
 ### -------------------------- Example 3: Creating markdown with specified paths --------------------------
 ```
 PS C:\> $PathToModule = "C:\azure-powershell\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.TrafficManager\AzureRM.TrafficManager.psd1"
 PS C:\> $PathToCommandsFolder = "C:\azure-powershell\src\ResourceManager\TrafficManager\Commands.TrafficManager2"
-PS C:\> $ModuleName = "AzureRM.TrafficManager"
-PS C:\> New-ServiceMarkdownHelp -PathToModule $PathToModule -PathToCommandsFolder $PathToCommandsFolder -ModuleName $ModuleName
+PS C:\> New-ServiceMarkdownHelp -PathToModule $PathToModule -PathToCommandsFolder $PathToCommandsFolder
 ```
 
 This example will create markdown help files for all of the TrafficManager cmdlets. The reason the ResourceManager parameter set is not used is because the commands folder path does not follow the format that this cmdlet is expecting: rather than ending in Commands.TrafficManager, it ends in Commands.TrafficManager2.
@@ -93,21 +89,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ModuleName
-The name of the service module that will be imported and used to create the markdown help for each cmdlet.
-
-```yaml
-Type: String
-Parameter Sets: FullPath
-Aliases: 
-
-Required: True
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -PathToCommandsFolder
 A path to the commands folder for the given service which contains the existing XML help (MAML), and will also contain the help folder with all of the markdown help files.
 
@@ -138,21 +119,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PathToRepo
-A path to the root of the azure-powershell repository that has been cloned.
-
-```yaml
-Type: String
-Parameter Sets: ServiceManagement, ResourceManager, Storage
-Aliases: 
-
-Required: True
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -ResourceManager
 Specifies that the service that help is being created for is ARM.
 

tools/platyPSHelp/help/Update-ServiceMarkdownHelp.md

@@ -13,25 +13,22 @@ This cmdlet will update markdown help files for each cmdlet in a given service,
 
 ### ServiceManagement
 ```
-Update-ServiceMarkdownHelp -Service <String> -BuildTarget <String> -PathToRepo <String> [-ServiceManagement]
- [<CommonParameters>]
+Update-ServiceMarkdownHelp -Service <String> -BuildTarget <String> [-ServiceManagement] [<CommonParameters>]
 ```
 
 ### ResourceManager
 ```
-Update-ServiceMarkdownHelp -Service <String> -BuildTarget <String> -PathToRepo <String> [-ResourceManager]
- [<CommonParameters>]
+Update-ServiceMarkdownHelp -Service <String> -BuildTarget <String> [-ResourceManager] [<CommonParameters>]
 ```
 
 ### Storage
 ```
-Update-ServiceMarkdownHelp -BuildTarget <String> -PathToRepo <String> [-Storage] [<CommonParameters>]
+Update-ServiceMarkdownHelp -BuildTarget <String> [-Storage] [<CommonParameters>]
 ```
 
 ### FullPath
 ```
-Update-ServiceMarkdownHelp -PathToModule <String> -PathToCommandsFolder <String> -ModuleName <String>
- [<CommonParameters>]
+Update-ServiceMarkdownHelp -PathToModule <String> -PathToCommandsFolder <String> [<CommonParameters>]
 ```
 
 ## DESCRIPTION
@@ -47,28 +44,27 @@ To ensure that the generated markdown help files have all of the necessary field
 
 ### -------------------------- Example 1: Updating markdown for an ARM service --------------------------
 ```
-PS C:\> Update-ServiceMarkdownHelp -Service Profile -BuildTarget Debug -PathToRepo C:\azure-powershell -ResourceManager
+PS C:\> Update-ServiceMarkdownHelp -Service Profile -BuildTarget Debug -ResourceManager
 ```
 
-This example will update markdown help files for all of the Profile cmdlets. It will import the Profile module from C:\azure-powershell\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.Profile\AzureRM.Profile.psd1. Then it will update the help files found on the same level as the XML help (MAML).
+This example will update markdown help files for all of the Profile cmdlets. It will import the Profile module from PATH_TO_REPO\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.Profile\AzureRM.Profile.psd1. Then it will update the help files found on the same level as the XML help (MAML).
 
-It will then regenerate the XML help (MAML) located at C:\azure-powershell\src\ResourceManager\Profile\Commands.Profile\Microsoft.Azure.Commands.Profile.dll-Help.xml.
+It will then regenerate the XML help (MAML) located at PATH_TO_REPO\src\ResourceManager\Profile\Commands.Profile\Microsoft.Azure.Commands.Profile.dll-Help.xml.
 
 ### -------------------------- Example 2: Updating markdown for Storage --------------------------
 ```
-PS C:\> Update-ServiceMarkdownHelp -BuildTarget Debug -PathToRepo C:\azure-powershell -Storage
+PS C:\> Update-ServiceMarkdownHelp -BuildTarget Debug -Storage
 ```
 
-This example will update markdown help files for all of the Storage cmdlets. It will import the Storage module from C:\azure-powershell\src\Package\Debug\Storage\Azure.Storage\Azure.Storage.psd1 and create a help folder in C:\azure-powershell\src\Storage\Commands.Storage. Then it will update the help files found on the same level as the XML help (MAML).
+This example will update markdown help files for all of the Storage cmdlets. It will import the Storage module from PATH_TO_REPO\src\Package\Debug\Storage\Azure.Storage\Azure.Storage.psd1. Then it will update the help files found on the same level as the XML help (MAML).
 
-It will also regenerate the XML help (MAML) located at C:\azure-powershell\src\Storage\Commands.Storage\Microsoft.WindowsAzure.Commands.Storage.dll-Help.xml.
+It will also regenerate the XML help (MAML) located at PATH_TO_REPO\src\Storage\Commands.Storage\Microsoft.WindowsAzure.Commands.Storage.dll-Help.xml.
 
 ### -------------------------- Example 3: Updating markdown with specified paths --------------------------
 ```
 PS C:\> $PathToModule = "C:\azure-powershell\src\Package\Debug\ResourceManager\AzureResourceManager\AzureRM.TrafficManager\AzureRM.TrafficManager.psd1"
 PS C:\> $PathToCommandsFolder = "C:\azure-powershell\src\ResourceManager\TrafficManager\Commands.TrafficManager2"
-PS C:\> $ModuleName = "AzureRM.TrafficManager"
-PS C:\> Update-ServiceMarkdownHelp -PathToModule $PathToModule -PathToCommandsFolder $PathToCommandsFolder -ModuleName $ModuleName
+PS C:\> Update-ServiceMarkdownHelp -PathToModule $PathToModule -PathToCommandsFolder $PathToCommandsFolder
 ```
 
 This example will update markdown help files for all of the TrafficManager cmdlets. The reason the ResourceManager parameter set is not used is because the commands folder path does not follow the format that this cmdlet is expecting: rather than ending in Commands.TrafficManager, it ends in Commands.TrafficManager2.
@@ -93,21 +89,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -ModuleName
-The name of the service module that will be imported and used to update the markdown help for each cmdlet.
-
-```yaml
-Type: String
-Parameter Sets: FullPath
-Aliases: 
-
-Required: True
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -PathToCommandsFolder
 A path to the commands folder for the given service which contains the existing XML help (MAML), and will also contain the help folder with all of the markdown help files.
 
@@ -138,21 +119,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PathToRepo
-A path to the root of the azure-powershell repository that has been cloned.
-
-```yaml
-Type: String
-Parameter Sets: ServiceManagement, ResourceManager, Storage
-Aliases: 
-
-Required: True
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -ResourceManager
 Specifies that the service that help is being updated for is ARM.
 

tools/platyPSHelp/help/Validate-ServiceMarkdownHelp.md

@@ -13,17 +13,17 @@ This cmdlet will validate that the markdown help for each cmdlet in a service ha
 
 ### ServiceManagement
 ```
-Validate-ServiceMarkdownHelp -Service <String> -PathToRepo <String> [-ServiceManagement] [<CommonParameters>]
+Validate-ServiceMarkdownHelp -Service <String> [-ServiceManagement] [<CommonParameters>]
 ```
 
 ### ResourceManager
 ```
-Validate-ServiceMarkdownHelp -Service <String> -PathToRepo <String> [-ResourceManager] [<CommonParameters>]
+Validate-ServiceMarkdownHelp -Service <String> [-ResourceManager] [<CommonParameters>]
 ```
 
 ### Storage
 ```
-Validate-ServiceMarkdownHelp -PathToRepo <String> [-Storage] [<CommonParameters>]
+Validate-ServiceMarkdownHelp [-Storage] [<CommonParameters>]
 ```
 
 ### FullPath
@@ -58,14 +58,14 @@ If any cmdlet is found to be missing help, Validate-ServiceMarkdownHelp will thr
 
 ### -------------------------- Example 1: Validating help for an ARM service --------------------------
 ```
-PS C:\> Validate-ServiceMarkdownHelp -Service Profile -PathToRepo C:\azure-powershell -ResourceManager
+PS C:\> Validate-ServiceMarkdownHelp -Service Profile -ResourceManager
 ```
 
 This example will validate the markdown help for the Profile cmdlets. It will find the help folder containing all of the markdown help and iterate over those files, checking if the necessary sections are filled out to completion.
 
 ### -------------------------- Example 2: Validating help for Storage --------------------------
 ```
-PS C:\> Validate-ServiceMarkdownHelp -PathToRepo C:\azure-powershell -Storage
+PS C:\> Validate-ServiceMarkdownHelp -Storage
 ```
 
 This example will validate the markdown help for the Storage cmdlets. It will find the help folder containing all of the markdown help and iterate over those files, checking if the necessary sections are filled out to completion.
@@ -111,21 +111,6 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -PathToRepo
-A path to the root of the azure-powershell repository that has been cloned.
-
-```yaml
-Type: String
-Parameter Sets: ServiceManagement, ResourceManager, Storage
-Aliases: 
-
-Required: True
-Position: Named
-Default value: None
-Accept pipeline input: False
-Accept wildcard characters: False
-```
-
 ### -ResourceManager
 Specifies that the service that help is being validated for is ARM.