You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: .github/PULL_REQUEST_TEMPLATE.md
+1-1Lines changed: 1 addition & 1 deletion
Original file line number
Diff line number
Diff line change
@@ -12,7 +12,7 @@ If applicable, reference the bug/issue that this pull request fixes here.
12
12
This checklist is used to make sure that common guidelines for a pull request are followed. You can find a more complete discussion of PowerShell cmdlet best practices [here](https://msdn.microsoft.com/en-us/library/dd878270(v=vs.85).aspx).
13
13
14
14
-[ ]**I have read the [contribution guidelines](https://github.com/Azure/azure-powershell/blob/dev/CONTRIBUTING.md).**
15
-
-[ ]**If changes were made to any cmdlet, the XML help was regenerated using the [platyPSHelp module](https://github.com/Azure/azure-powershell/blob/dev/documentation/platyps-help.md).**
15
+
-[ ]**If changes were made to any cmdlet, the XML help was regenerated using the [platyPSHelp module](https://github.com/Azure/azure-powershell/blob/dev/documentation/platyPSHelp-documentation.md).**
16
16
-[ ]**If any large changes are made to a service, they are reflected in the respective [change log](https://github.com/Azure/azure-powershell/blob/dev/CONTRIBUTING.md#updating-the-change-log).**
Copy file name to clipboardExpand all lines: documentation/Repo-Tasks-Module.md
+3-3Lines changed: 3 additions & 3 deletions
Original file line number
Diff line number
Diff line change
@@ -2,8 +2,8 @@
2
2
3
3
###### Usage:
4
4
5
-
1. Start PS-VSPrompt.lnk (shortcut), this will start VS Dev Prompt in powershell
6
-
2. Import-Module ./Repo-Tasks.psm1
5
+
1. Start .\tools\PS-VSPrompt.lnk (shortcut), this will start VS Dev Prompt in powershell
6
+
2. Import-Module .\tools\Repo-Tasks.psd1
7
7
1. During import, we allow to load additional functions that users might want to use it in their session.
8
8
2. If you have any userPreference.ps1 file under %userprofile%/psFiles directory, the module will try to load it by dot sourcing it.
9
9
2. It will also honor environment variable $env:psuserpreferences and load .ps1 files from the location that is pointed by $env:psuserpreferences
@@ -20,4 +20,4 @@
20
20
1. Will build and run existing tests.
21
21
22
22
###Note:
23
-
If you do not start your powershell session using PS-VSPrompt shortcut, you will not have access to all the environment variables that are set as part of VS Dev Command prompt.
23
+
If you do not start your powershell session using PS-VSPrompt shortcut, you will not have access to all the environment variables that are set as part of VS Dev Command prompt.
Copy file name to clipboardExpand all lines: documentation/platyPSHelp-documentation.md
+44-13Lines changed: 44 additions & 13 deletions
Original file line number
Diff line number
Diff line change
@@ -1,8 +1,11 @@
1
1
# PlatyPS Help
2
2
3
3
-[Description](#description)
4
+
-[Prerequisites](#prerequisites)
5
+
-[Install and import platyPS](#install-and-import-platyps)
6
+
-[Check for valid paths](#check-for-valid-paths)
4
7
-[Getting Started](#getting-started)
5
-
-[Installing the platyPSHelp Module](#installing-the-platypshelp-module)
8
+
-[Installing the platyPSHelp module](#installing-the-platypshelp-module)
6
9
-[Running the New-ServiceMarkdownHelp cmdlet](#running-the-new-servicemarkdownhelp-cmdlet)
7
10
-[Running the Validate-ServiceMarkdownHelp cmdlet](#running-the-validate-servicemarkdownhelp-cmdlet)
8
11
-[Running the Update-ServiceMarkdownHelp cmdlet](#running-the-update-servicemarkdownhelp-cmdlet)
@@ -20,15 +23,44 @@
20
23
21
24
PlatyPS is used to create PowerShell external help in markdown rather than XML (MAML). Where as XML help (MAML) can be difficult to edit by hand or read, markdown is designed to be human-readable and easy to edit. This will allow service teams to quickly and easily edit any help documentation they have for their cmdlets.
22
25
23
-
Install (and read more about) platyPS from the README, located [here](https://github.com/PowerShell/platyPS/blob/master/README.md).
26
+
You can find the more information on platyPS [here](https://github.com/PowerShell/platyPS/blob/master/README.md).
27
+
28
+
The platyPSHelp module uses platyPS to allow service teams to achieve the following:
29
+
- Create markdown files for each of their cmdlets
30
+
- Update the markdown files when changes are made to the cmdlets
31
+
- Validate the help content in the markdown files to ensure no sections are missing information
32
+
33
+
## Prerequisites
34
+
35
+
### Install and import the platyPS
36
+
37
+
In order to use the platyPSHelp module, you will first need to install the platyPS module. To do so, run the following commands:
38
+
39
+
```powershell
40
+
Install-Module -Name platyPS -Scope CurrentUser
41
+
Import-Module platyPS
42
+
```
43
+
44
+
### Check for valid paths
45
+
46
+
The platyPSHelp module builds paths to the service module and commands directory using the service name provided, the build target, and if the service is ARM or RDFE.
47
+
48
+
For ARM services, these paths include:
49
+
- Path to module: `src\Package\<Build Target>\ResourceManager\AzureResourceManager\AzureRM.<Service>\AzureRM.<Service>.psd1`
50
+
- Path to commands: `src\ResourceManager\<Service>\Commands.<Service>`
51
+
- Path to help: `src\ResourceManager\<Service>\Commands.<Service>\help`
52
+
53
+
TrafficManager, for example, is a service that doesn't follow the format of these paths that are built - the path to their commands folder is `src\ResourceManager\TrafficManager\Commands.TrafficManager2`.
54
+
55
+
In the case that your service doesn't follow the format of the above paths, you will need to use the "FullPath" parameter set, which allows you to pass in the paths as parameters rather than have them built.
24
56
25
57
## Getting Started
26
58
27
59
If your service does not currently have any markdown help, follow the below steps to get started.
28
60
29
61
**NOTE**: Currently, the platyPSHelp module mentioned below is unable to create markdown help for **ServiceManagement** cmdlets. However, markdown help can be created for these cmdlets when running the regular platyPS cmdlets mentioned in the [How it Works](#how-it-works) section.
30
62
31
-
### Installing the `platyPSHelp` Module
63
+
### Installing the platyPSHelp module
32
64
33
65
The `platyPSHelp` module contains cmdlets that will help service teams with creating, updating, and validating markdown help for their cmdlets.
34
66
@@ -39,15 +71,20 @@ There are three cmdlets contained in this module:
39
71
40
72
Help documentation has been written for each of these cmdlets, outlining the purpose of each cmdlet, the different parameter sets, and examples.
41
73
42
-
To use this module, change your directory to the **azure-powershell** repo, and from there, go to `tools\platyPS`. Run the following command to import the module:
74
+
To use this module, change your directory to the **azure-powershell** repo, and from there, go to `tools\platyPSHelp`. Run the following command to import the module:
43
75
44
76
```powershell
45
77
Import-Module .\platyPSHelp.psd1
46
78
```
47
79
48
80
After executing this command, you will have access to the above cmdlets.
49
81
50
-
### Running the `New-ServiceMarkdownHelp` cmdlet
82
+
If you are not using the "FullPath" parameter set, you will need the following information to use the cmdlets:
83
+
-`Service` - the name of the service
84
+
-`BuildTarget` - either Build or Release, the type of build used when building the service project locally
85
+
-`ModuleName` - the name of the module corresponding to the service (_i.e._, AzureRM.Profile)
86
+
87
+
### Running the [New-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/New-ServiceMarkdownHelp.md) cmdlet
51
88
52
89
Once the module is installed, you will need to generate the markdown for your cmdlets; to do so, you will run the `New-ServiceMarkdownHelp` cmdlet.
53
90
@@ -61,16 +98,12 @@ There are four possible parameter sets to choose from when creating your cmdlets
61
98
-`FullPath`
62
99
- 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
63
100
64
-
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).
65
-
66
101
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.
67
102
68
-
### Running the `Validate-ServiceMarkdownHelp` cmdlet
103
+
### Running the [Validate-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Validate-ServiceMarkdownHelp.md) cmdlet
69
104
70
105
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).
71
106
72
-
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).
73
-
74
107
Once ran, this cmdlet will output a list of errors for each cmdlet in the following format:
75
108
76
109
```
@@ -87,12 +120,10 @@ File: Some-Cmdlet.md
87
120
88
121
This will let you know what parts of the markdown help need to be updated. A recommended tool for editing and visualizing markdown is [Dillinger](http://dillinger.io/), which will display your markdown changes in real-time.
89
122
90
-
### Running the `Update-ServiceMarkdownHelp` cmdlet
123
+
### Running the [Update-ServiceMarkdownHelp](https://github.com/Azure/azure-powershell/blob/dev/tools/platyPSHelp/help/Update-ServiceMarkdownHelp.md) cmdlet
91
124
92
125
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.
93
126
94
-
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).
95
-
96
127
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.
0 commit comments