Skip to content

Commit 7834071

Browse files
adityapatwardhanadityapatwardhan
committed
Add tests
1 parent 8d2365d commit 7834071

File tree

5 files changed

+268
-11
lines changed

5 files changed

+268
-11
lines changed

‎src/platyPS/platyPS.psm1

+40-11
Original file line numberDiff line numberDiff line change
@@ -834,7 +834,7 @@ function New-ExternalHelp
834834

835835
process
836836
{
837-
$MarkdownFiles += GetMarkdownFilesFromPath $Path
837+
$MarkdownFiles += FilterMdFileToExcludeModulePage -Path (GetMarkdownFilesFromPath $Path)
838838

839839
if($MarkdownFiles)
840840
{
@@ -1481,6 +1481,35 @@ function GetAboutTopicsFromPath
14811481
return $AboutMarkDownFiles
14821482
}
14831483

1484+
function FilterMdFileToExcludeModulePage {
1485+
[CmdletBinding()]
1486+
param(
1487+
[Parameter(Mandatory = $true)]
1488+
[System.IO.FileInfo[]]$Path
1489+
)
1490+
1491+
$MarkdownFiles = @()
1492+
1493+
if ($Path) {
1494+
$Path | ForEach-Object {
1495+
if (Test-Path $_) {
1496+
$md = Get-Content -Raw -Path $_
1497+
$yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md)
1498+
$isModulePage = $null -ne $yml.'Module Guid'
1499+
1500+
if (-not $isModulePage) {
1501+
$MarkdownFiles += $_
1502+
}
1503+
}
1504+
else {
1505+
Write-Error -Message ($LocalizedData.PathNotFound -f $_)
1506+
}
1507+
}
1508+
}
1509+
1510+
return $MarkdownFiles
1511+
}
1512+
14841513
function GetMarkdownFilesFromPath
14851514
{
14861515
[CmdletBinding()]
@@ -1492,6 +1521,15 @@ function GetMarkdownFilesFromPath
14921521
[switch]$IncludeModulePage
14931522
)
14941523

1524+
if ($IncludeModulePage)
1525+
{
1526+
$filter = '*.md'
1527+
}
1528+
else
1529+
{
1530+
$filter = '*-*.md'
1531+
}
1532+
14951533
$aboutFilePrefixPattern = 'about_*'
14961534

14971535
$MarkdownFiles = @()
@@ -1506,16 +1544,7 @@ function GetMarkdownFilesFromPath
15061544
}
15071545
elseif (Test-Path -PathType Container $_)
15081546
{
1509-
$MarkdownFiles += Get-ChildItem $_ -File | ForEach-Object {
1510-
$md = Get-Content -Raw -Path $_
1511-
$yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md)
1512-
$isModulePage = $null -ne $yml.'Module Guid'
1513-
1514-
if ($IncludeModulePage -and $isModulePage -or -not $isModulePage -and -not $IncludeModulePage)
1515-
{
1516-
$_ | Where-Object {$_.BaseName -notlike $aboutFilePrefixPattern}
1517-
}
1518-
}
1547+
$MarkdownFiles += Get-ChildItem $_ -Filter $filter | Where-Object {$_.BaseName -notlike $aboutFilePrefixPattern}
15191548
}
15201549
else
15211550
{

‎test/Pester/PlatyPs.Tests.ps1

+13
Original file line numberDiff line numberDiff line change
@@ -723,6 +723,8 @@ Describe 'New-ExternalHelp' {
723723
}
724724
$file = New-MarkdownHelp -Command 'Test-OrderFunction' -OutputFolder $TestDrive -Force
725725
$maml = $file | New-ExternalHelp -OutputPath "$TestDrive\TestOrderFunction.xml" -Force
726+
727+
$extHelp = New-ExternalHelp -Path "$PSScriptRoot/assets/ModuleWithDash" -OutputPath "$TestDrive\ModuleWithDash"
726728
}
727729

728730
It "generates right order for syntax" {
@@ -739,6 +741,10 @@ Describe 'New-ExternalHelp' {
739741
$xml = [xml] (Get-Content (Join-Path $TestDrive 'TestOrderFunction.xml'))
740742
$xml.helpItems.namespaceuri | Should Be 'http://msh'
741743
}
744+
745+
It 'checks that external help can be generated for modules with dash in it' {
746+
$extHelp | Should -Exist
747+
}
742748
}
743749

744750
Describe 'New-ExternalHelp -ErrorLogFile' {
@@ -1612,4 +1618,11 @@ Describe 'New-YamlHelp' {
16121618
It 'throws for OutputFolder that is a file'{
16131619
{ New-YamlHelp "$root\docs\New-YamlHelp.md" -OutputFolder "$outFolder\yaml\New-YamlHelp.yml" } | Should Throw
16141620
}
1621+
1622+
It 'does not omit # in output type names' {
1623+
1624+
New-YamlHelp "$PSScriptRoot\assets\New-YamlHelp.md" -OutputFolder "$TestDrive\yaml" -Force
1625+
1626+
Get-Content 'D:\temp\yaml\New-YamlHelp.yml' | Should -Contain '- type: IResult\#System.IO.FileInfo[]'
1627+
}
16151628
}

‎test/Pester/assets/ModuleWithDash/Test-Module.md

+16
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
Module Name: Test-Module
3+
Module Guid: ad057547-0b77-49d0-b8dd-9ffd6d44b0be
4+
Download Help Link: {{ Update Download Link }}
5+
Help Version: {{ Please enter version of help manually (X.X.X.X) format }}
6+
Locale: en-US
7+
---
8+
9+
# Test-Module Module
10+
## Description
11+
{{ Fill in the Description }}
12+
13+
## Test-Module Cmdlets
14+
### [Test-ModuleCmdlet](Test-ModuleCmdlet.md)
15+
{{ Fill in the Description }}
16+

‎test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
external help file: Test-Module-help.xml
3+
Module Name: Test-Module
4+
online version:
5+
schema: 2.0.0
6+
title: Test-ModuleCmdlet
7+
---
8+
9+
# Test-ModuleCmdlet
10+
11+
## SYNOPSIS
12+
{{ Fill in the Synopsis }}
13+
14+
## SYNTAX
15+
16+
```
17+
Test-ModuleCmdlet [<CommonParameters>]
18+
```
19+
20+
## DESCRIPTION
21+
{{ Fill in the Description }}
22+
23+
## EXAMPLES
24+
25+
### Example 1
26+
```powershell
27+
PS C:\> {{ Add example code here }}
28+
```
29+
30+
{{ Add example description here }}
31+
32+
## PARAMETERS
33+
34+
### CommonParameters
35+
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).
36+
37+
## INPUTS
38+
39+
### None
40+
41+
## OUTPUTS
42+
43+
### System.Object
44+
## NOTES
45+
46+
## RELATED LINKS

‎test/Pester/assets/New-YamlHelp.md

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
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+
### IResult#System.IO.FileInfo[]
149+
This cmdlet returns a **FileInfo[]** object for created files.
150+
151+
## NOTES
152+
153+
## RELATED LINKS

0 commit comments

Comments
 (0)