Skip to content

Commit b89efd8

Browse files
Sampyadityapatwardhan
Sampy
authored and
adityapatwardhan
committed
Adding New-YamlHelp cmdlet as well as adding module data to cmdlet pages (#277)
* Adding New-YamlHelp cmdlet as well as adding module data to cmdlet markdown pages * Responding to code review feedback (part 1) * More code review feedback responses * Adding platyPS tests for New-YamlHelp * Removing yaml folder
1 parent 97a3b52 commit b89efd8

27 files changed

+775
-7
lines changed

‎build.ps1

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -14,17 +14,22 @@ if (-not (Get-Command -Name msbuild -ErrorAction Ignore)) {
1414
}
1515

1616
msbuild Markdown.MAML.sln /p:Configuration=$Configuration
17-
$assemblyPath = (Resolve-Path "src\Markdown.MAML\bin\$Configuration\Markdown.MAML.dll").Path
17+
$assemblyPaths = ((Resolve-Path "src\Markdown.MAML\bin\$Configuration\Markdown.MAML.dll").Path, (Resolve-Path "src\Markdown.MAML\bin\$Configuration\YamlDotNet.dll").Path)
1818

1919
# copy artifacts
2020
mkdir out -ErrorAction SilentlyContinue > $null
2121
cp -Rec -Force src\platyPS out
22-
if (-not (Test-Path out\platyPS\Markdown.MAML.dll) -or
23-
(ls out\platyPS\Markdown.MAML.dll).LastWriteTime -lt (ls $assemblyPath).LastWriteTime)
22+
foreach($assemblyPath in $assemblyPaths)
2423
{
25-
cp $assemblyPath out\platyPS
26-
} else {
27-
Write-Host -Foreground Yellow 'Skip Markdown.MAML.dll copying'
24+
$assemblyFileName = [System.IO.Path]::GetFileName($assemblyPath)
25+
$outputPath = "out\platyPS\$assemblyFileName"
26+
if ((-not (Test-Path $outputPath)) -or
27+
(Test-Path $outputPath -OlderThan (ls $assemblyPath).LastWriteTime))
28+
{
29+
cp $assemblyPath out\platyPS
30+
} else {
31+
Write-Host -Foreground Yellow "Skip $assemblyFileName copying"
32+
}
2833
}
2934

3035
# copy schema file and docs

‎docs/Get-HelpPreview.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/Get-HelpPreview.md
45
schema: 2.0.0
56
---

‎docs/Get-MarkdownMetadata.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/Get-MarkdownMetadata.md
45
schema: 2.0.0
56
---

‎docs/New-ExternalHelp.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelp.md
45
schema: 2.0.0
56
---

‎docs/New-ExternalHelpCab.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-ExternalHelpCab.md
45
schema: 2.0.0
56
---

‎docs/New-MarkdownAboutHelp.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownAboutHelp.md
45
schema: 2.0.0
56
---

‎docs/New-MarkdownHelp.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-MarkdownHelp.md
45
schema: 2.0.0
56
---

‎docs/New-YamlHelp.md

Lines changed: 154 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
---
2+
external help file: platyPS-help.xml
3+
Module Name: platyPS
4+
online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-YamlHelp.md
5+
schema: 2.0.0
6+
---
7+
8+
# New-YamlHelp
9+
10+
## SYNOPSIS
11+
Converts Markdown help into YAML to be read easily by external tools
12+
13+
## SYNTAX
14+
15+
```
16+
New-YamlHelp [-Path] <String[]> -OutputFolder <String> [-Encoding <Encoding>] [-Force] [<CommonParameters>]
17+
```
18+
19+
## DESCRIPTION
20+
The **New-YamlHelp** cmdlet works similarly to the **New-ExternalHelp** cmdlet but rather than creating a MAML file to support **Get-Help**, it creates a set of YAML files that can be read by external tools to provide custom rendering of help pages.
21+
22+
## EXAMPLES
23+
24+
### Example 1: Create YAML files
25+
```
26+
PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml
27+
28+
Directory: D:\Working\PlatyPS\out\yaml
29+
30+
31+
Mode LastWriteTime Length Name
32+
---- ------------- ------ ----
33+
-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml
34+
-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml
35+
-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml
36+
-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml
37+
-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml
38+
-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml
39+
-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml
40+
-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml
41+
-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml
42+
-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml
43+
```
44+
45+
This creates one YAML file for each cmdlet so external tools can read the structured data for each cmdlet.
46+
47+
### Example 2: Create YAML files with specific encoding
48+
```
49+
PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml -Force -Encoding ([System.Text.Encoding]::Unicode)
50+
51+
Directory: D:\Working\PlatyPS\out\yaml
52+
53+
54+
Mode LastWriteTime Length Name
55+
---- ------------- ------ ----
56+
-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml
57+
-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml
58+
-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml
59+
-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml
60+
-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml
61+
-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml
62+
-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml
63+
-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml
64+
-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml
65+
-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml
66+
```
67+
68+
This will both read and write the files in the specified -Encoding.
69+
The -Force parameter will overwrite files that already exist.
70+
71+
## PARAMETERS
72+
73+
### -Encoding
74+
Specifies the character encoding for your external help file.
75+
Specify a **System.Text.Encoding** object.
76+
For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network.
77+
For example, you can control Byte Order Mark (BOM) preferences.
78+
For more information, see [Using PowerShell to write a file in UTF-8 without the BOM](http://stackoverflow.com/questions/5596982/using-powershell-to-write-a-file-in-utf-8-without-the-bom) at the Stack Overflow community.
79+
80+
```yaml
81+
Type: Encoding
82+
Parameter Sets: (All)
83+
Aliases:
84+
85+
Required: False
86+
Position: Named
87+
Default value: None
88+
Accept pipeline input: False
89+
Accept wildcard characters: False
90+
```
91+
92+
### -Force
93+
Indicates that this cmdlet overwrites an existing file that has the same name.
94+
95+
```yaml
96+
Type: SwitchParameter
97+
Parameter Sets: (All)
98+
Aliases:
99+
100+
Required: False
101+
Position: Named
102+
Default value: None
103+
Accept pipeline input: False
104+
Accept wildcard characters: False
105+
```
106+
107+
### -Path
108+
Specifies an array of paths of markdown files or folders.
109+
This cmdlet creates external help based on these files and folders.
110+
111+
```yaml
112+
Type: String[]
113+
Parameter Sets: (All)
114+
Aliases:
115+
116+
Required: True
117+
Position: 1
118+
Default value: None
119+
Accept pipeline input: True (ByPropertyName, ByValue)
120+
Accept wildcard characters: False
121+
```
122+
123+
### -OutputFolder
124+
Specifies the folder to create the YAML files in
125+
126+
```yaml
127+
Type: String
128+
Parameter Sets: (All)
129+
Aliases:
130+
131+
Required: True
132+
Position: Named
133+
Default value: None
134+
Accept pipeline input: False
135+
Accept wildcard characters: False
136+
```
137+
138+
### CommonParameters
139+
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
140+
141+
## INPUTS
142+
143+
### System.String[]
144+
You can pipe an array of paths to this cmdlet.
145+
146+
## OUTPUTS
147+
148+
### System.IO.FileInfo[]
149+
This cmdlet returns a **FileInfo[]** object for created files.
150+
151+
## NOTES
152+
153+
## RELATED LINKS
154+

‎docs/Update-MarkdownHelp.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelp.md
45
schema: 2.0.0
56
---

‎docs/Update-MarkdownHelpModule.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
---
22
external help file: platyPS-help.xml
3+
Module Name: platyPS
34
online version: https://github.com/PowerShell/platyPS/blob/master/docs/Update-MarkdownHelpModule.md
45
schema: 2.0.0
56
---

0 commit comments

Comments
 (0)