Skip to content

Commit f705bee

Browse files
huangpfhuangpf
authored
Merge pull request #628 from Azure/dev
huangpf PR: dev <- Azure:dev
2 parents 3eba3f8 + afa7cb0 commit f705bee

23 files changed

+6886
-2318
lines changed

‎documentation/platyps-help.md

Lines changed: 288 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,288 @@
1+
# PlatyPS Help
2+
3+
- [Description](#description)
4+
- [Getting Started](#getting-started)
5+
- [Installing the platyPSHelp Module](#installing-the-platypshelp-module)
6+
- [Running the New-ServiceMarkdownHelp cmdlet](#running-the-new-servicemarkdownhelp-cmdlet)
7+
- [Running the Validate-ServiceMarkdownHelp cmdlet](#running-the-validate-servicemarkdownhelp-cmdlet)
8+
- [Running the Update-ServiceMarkdownHelp cmdlet](#running-the-update-servicemarkdownhelp-cmdlet)
9+
- [How it Works](#how-it-works)
10+
- [Creating markdown](#creating-markdown)
11+
- [Updating markdown](#updating-markdown)
12+
- [Updating XML help](#updating-xml-help)
13+
- [Previewing XML help](#previewing-xml-help)
14+
- [Steps for creating help](#steps-for-creating-help)
15+
- [Changes to Cmdlets](#changes-to-cmdlets)
16+
- [Markdown Format](#markdown-format)
17+
- [Issue with Example Formatting](#issue-with-example-formatting)
18+
19+
## Description
20+
21+
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+
23+
Install (and read more about) platyPS from the README, located [here](https://github.com/PowerShell/platyPS/blob/master/README.md).
24+
25+
## Getting Started
26+
27+
If your service does not currently have any markdown help, follow the below steps to get started.
28+
29+
**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+
31+
### Installing the `platyPSHelp` Module
32+
33+
The `platyPSHelp` module contains cmdlets that will help service teams with creating, updating, and validating markdown help.
34+
35+
There are three cmdlets contained in this module:
36+
- `New-ServiceMarkdownHelp`
37+
- `Update-ServiceMarkdownHelp`
38+
- `Validate-ServiceMarkdownHelp`
39+
40+
Help documentation has been written for each of these cmdlets, outlining the purpose of each cmdlet, the different parameter sets, and examples.
41+
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:
43+
44+
```powershell
45+
Import-Module .\platyPSHelp.psd1
46+
```
47+
48+
After executing this command, you will have access to the above cmdlets.
49+
50+
### Running the `New-ServiceMarkdownHelp` cmdlet
51+
52+
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+
54+
There are four possible parameter sets to choose from when creating your cmdlets:
55+
- `ResourceManager`
56+
- This parameter set will be used if you are an ARM service
57+
- `ServiceManagement`
58+
- This parameter set will be used if you are an RDFE service
59+
- `Storage`
60+
- This parameter set will be used for the Storage team
61+
- `FullPath`
62+
- 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+
64+
More information about this cmdlet can be found in the [help]("..\tools\platyPSHelp\help\New-ServiceMarkdownHelp.md").
65+
66+
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+
68+
### Running the `Validate-ServiceMarkdownHelp` cmdlet
69+
70+
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+
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]("..\tools\platyPSHelp\help\Validate-ServiceMarkdownHelp.md").
73+
74+
Once ran, this cmdlet will output a list of errors for each cmdlet in the following format:
75+
76+
```
77+
==========
78+
79+
File: Some-Cmdlet.md
80+
81+
-- No description found
82+
-- No examples found
83+
-- No description found for parameter Foo
84+
85+
==========
86+
```
87+
88+
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+
90+
### Running the `Update-ServiceMarkdownHelp` cmdlet
91+
92+
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+
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]("..\tools\platyPSHelp\help\Update-ServiceMarkdownHelp.md").
95+
96+
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.
97+
98+
## How it Works
99+
100+
### Creating markdown
101+
102+
Using the `New-MarkdownHelp` cmdlet, platyPS generates a markdown file for each cmdlet in a XML help (MAML) file and/or module, depending on the parameters of the call.
103+
104+
For instance, if the following command is called
105+
```powershell
106+
New-MarkdownHelp -OutputFolder $PathToHelp -MamlFile $MAML
107+
```
108+
then the markdown files will be generated from the information in the XML help (MAML) file.
109+
110+
However, if the following command is called
111+
```powershell
112+
New-MarkdownHelp -OutputFolder $PathToHelp -Module $ModuleName -WithModulePage
113+
```
114+
then the markdown files will be generated from the information in the XML help (MAML) file (found in the module) **and** using reflection on the cmdlet implementation in the module.
115+
116+
#### NOTE
117+
118+
Please refer to the [Issue with Example Formatting](#issue-with-example-formatting) section at the bottom to resolve a problem found in cmdlets using rows and columns for variable data in their examples.
119+
120+
### Updating markdown
121+
122+
Once you have created the markdown files for each cmdlet, you must make sure to keep them up to date based on changes to the cmdlets.
123+
124+
The **recommended** way to update the markdown files is to use the cmdlet `Update-MarkdownHelpModule`; this method handles both changes to cmdlets **and** the addition of cmdlets. Use the following command:
125+
```powershell
126+
Update-MarkdownHelpModule -Path $PathToHelp
127+
```
128+
where `$PathToHelp` is the path to the folder containing all of the markdown help.
129+
130+
This command updates all the files in the specified folder based on the cmdlets as loaded into your current session. It is the same as calling `New-MarkdownHelp` and `Update-MarkdownHelp` and merging the results together.
131+
132+
If any changes are made to a cmdlet (*i.e.,* add/remove parameters, add/remove parameter sets, etc.), the corresponding markdown can be updated through reflection by using the following command
133+
```powershell
134+
Update-MarkdownHelp -Path $PathToHelp
135+
```
136+
where `$PathToHelp` is the path to the folder containing all of the markdown help.
137+
138+
If a cmdlet is added to your module, then the above command will not work; you must first add the corresponding markdown file by running the following command (also used in the previous section):
139+
```powershell
140+
New-MarkdownHelp -OutputFolder $output -Module $module -WithModulePage
141+
```
142+
143+
### Updating XML help
144+
145+
After you have created or updated your markdown for the cmdlets, you need to update the XML help (MAML) so it can be used with `Get-Help` in PowerShell.
146+
147+
Updating XML help (MAML) can be done with the following command:
148+
```powershell
149+
New-ExternalHelp -Path $path -OutputPath $outputPath -Force
150+
```
151+
where `$path` is the path to the folder containing all of the markdown help, and `$outputPath` is the path to the folder containing the existing XML help (MAML) which will be replaced.
152+
153+
This command generates the XML help (MAML) based solely on the markdown files. All the information from the cmdlets (thru reflection) are already incorporated into the markdown thru `New-MarkdownHelp` and `Update-MarkdownHelp` (or `Update-MarkdownHelpModule`). This means that you won't need to build/install/import modules to generate help for them.
154+
155+
### Previewing XML help
156+
157+
After you have created or updated your markdown for the cmdlets, you can preview what the corresponding XML help (MAML) will look like in PowerShell with the `Get-HelpPreview` cmdlet. This cmdlet will generate the XML help (MAML) from the markdown files and display it in PowerShell so you can see if the help looks correct.
158+
159+
Running the following command will display the help for **all** of your cmdlets:
160+
```powershell
161+
Get-HelpPreview -Path $PathToMAML
162+
```
163+
where `$PathToMAML` is the path to the XML help (MAML) help file you generated.
164+
165+
To get the help for a single cmdlet, run the following command:
166+
```powershell
167+
$Help = Get-HelpPreview -Path $PathToMAML
168+
$Help | Where-Object { $_.Name -eq $CmdletName }
169+
```
170+
171+
### Steps for creating help
172+
173+
The following is a breakdown of the steps taken by the `New-ServiceMarkdownHelp` cmdlet
174+
175+
**1: Create a folder for your service**
176+
177+
In the `azure-powershell` repository, navigate to the `help` folder in the root, and, if your service does not already have one, create a new folder that will hold the markdown files for your service
178+
179+
**2: Import your module**
180+
181+
Run the following command in PowerShell:
182+
183+
```powershell
184+
Import-Module $PathToModule
185+
```
186+
where `$PathToModule` is the path to the psd1 file for the project that was just built
187+
188+
**3: Generate the markdown files**
189+
190+
Run the following command in PowerShell:
191+
192+
```powershell
193+
New-MarkdownHelp -Module $ModuleName -OutputFolder $PathToHelp -WithModulePage -AlphabeticParamsOrder
194+
```
195+
where `$ModuleName` is the name of your module, and `$PathToHelp` is the path to the folder where the markdown help will be placed (which should be on the same level as the XML help (MAML))
196+
197+
This will generate a markdown file for each cmdlet in your XML help (MAML) file. Make sure that all of the cmdlets that you have help for in the XML help (MAML) file have a corresponding markdown file in the folder.
198+
199+
**4: Generate the XML help file**
200+
201+
Run the following command in PowerShell:
202+
203+
```powershell
204+
New-ExternalHelp -Path $PathToHelp -OutputPath $PathToCommandsFolder -Force
205+
```
206+
where `$PathToHelp` is the path to the folder containing the markdown help, and `$PathToCommandsFolder` is the path to the folder containing the XML help (MAML) and the help folder
207+
208+
This will generate a XML help (MAML) file based on the markdown files that you created in the previous step and replace the old XML help (MAML) file.
209+
210+
## Changes to Cmdlets
211+
212+
The following changes to a cmdlet require that the corresponding markdown help file be updated:
213+
214+
- Adding/removing parameters or parameter sets
215+
- Adding/removing cmdlets
216+
- Changing metadata of the cmdlet, parameters, or parameter sets
217+
218+
Begin with the following tasks:
219+
- Build your project
220+
- Open a new PowerShell window and import your project
221+
222+
Next, run the following command:
223+
224+
```powershell
225+
Update-MarkdownHelpModule $PathToHelp
226+
```
227+
where `$PathToHelp` is the path to the folder containing the markdown help
228+
229+
This will automatically update your markdown files with the changes that you have made in your cmdlets.
230+
231+
**Note**: check to make sure that the changes you made to the cmdlets are reflected in their corresponding markdown files
232+
233+
After generating the updated markdown files, make sure to generate the updated XML help (MAML) file by running the following command:
234+
235+
```powershell
236+
New-ExternalHelp -Path $PathToHelp -OutputPath $PathToCommandsFolder -Force
237+
```
238+
where `$PathToHelp` is the path to the folder containing the markdown help, and `$PathToCommandsFolder` is the path to the folder containing the XML help (MAML) and the help folder
239+
240+
## Markdown Format
241+
242+
If you want to edit the markdown files to add or remove your own help, there is a specified format that they need to follow in order to generate the corresponding XML help (MAML) help. A full guide for how the markdown file should be formatted can be found [here](https://github.com/PowerShell/platyPS/blob/master/platyPS.schema.md#version-200).
243+
244+
The following sections should be filled out for each cmdlet:
245+
- SYNOPSIS
246+
- Gives a short overview of what the cmdlet does
247+
- DESCRIPTION
248+
- An in-depth overview of what the cmdlet does
249+
- EXAMPLES
250+
- Shows how to use the cmdlet with different parameter sets and describes how they function differently
251+
- OUTPUTS
252+
- Defines what the output of the cmdlet is (what is sent out to the pipeline)
253+
254+
## Issue with Example Formatting
255+
256+
Some cmdlets have examples containing rows and columns of information after the PowerShell commands and remarks. For example:
257+
258+
### -------------------------- Example 1: Get capabilities for the current subscription for a region --------------------------
259+
@{paragraph=PS C:\\\>}
260+
261+
```
262+
PS C:\> Get-AzureRmSqlCapability -LocationName "Central US"
263+
```
264+
265+
This command returns the capabilities for SQL Database on the current subscription for the Central US region.
266+
267+
Location : Central US
268+
Status : Available
269+
SupportedServerVersions : {12.0, 2.0}
270+
271+
However, the format of these rows and columns are not preserved when platyPS generates the XML help (MAML). In order to avoid this issue, please move the rows and columns into the code block of the example; this is how help for core PowerShell modules is written.
272+
273+
After making these changes, the resulting markdown would look like the following:
274+
275+
### -------------------------- Example 1: Get capabilities for the current subscription for a region --------------------------
276+
@{paragraph=PS C:\\\>}
277+
278+
```
279+
PS C:\> Get-AzureRmSqlCapability -LocationName "Central US"
280+
281+
Location : Central US
282+
Status : Available
283+
SupportedServerVersions : {12.0, 2.0}
284+
```
285+
286+
This command returns the capabilities for SQL Database on the current subscription for the Central US region.
287+
288+
Making these changes will allow the table to preserve the format when the XML help (MAML) is displayed in the PowerShell window.

0 commit comments

Comments
 (0)