From 80049b18439bcbd69f5ff7ca52cd03382072b162 Mon Sep 17 00:00:00 2001 From: Aditya Patwardhan Date: Wed, 16 Jun 2021 16:58:30 -0700 Subject: [PATCH] Add tests --- src/platyPS/platyPS.psm1 | 51 ++++-- test/Pester/PlatyPs.Tests.ps1 | 13 ++ .../assets/ModuleWithDash/Test-Module.md | 16 ++ .../ModuleWithDash/Test-ModuleCmdlet.md | 46 ++++++ test/Pester/assets/New-YamlHelp.md | 153 ++++++++++++++++++ 5 files changed, 268 insertions(+), 11 deletions(-) create mode 100644 test/Pester/assets/ModuleWithDash/Test-Module.md create mode 100644 test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md create mode 100644 test/Pester/assets/New-YamlHelp.md diff --git a/src/platyPS/platyPS.psm1 b/src/platyPS/platyPS.psm1 index b18a9d41..328419e3 100644 --- a/src/platyPS/platyPS.psm1 +++ b/src/platyPS/platyPS.psm1 @@ -834,7 +834,7 @@ function New-ExternalHelp process { - $MarkdownFiles += GetMarkdownFilesFromPath $Path + $MarkdownFiles += FilterMdFileToExcludeModulePage -Path (GetMarkdownFilesFromPath $Path) if($MarkdownFiles) { @@ -1481,6 +1481,35 @@ function GetAboutTopicsFromPath return $AboutMarkDownFiles } +function FilterMdFileToExcludeModulePage { + [CmdletBinding()] + param( + [Parameter(Mandatory = $true)] + [System.IO.FileInfo[]]$Path + ) + + $MarkdownFiles = @() + + if ($Path) { + $Path | ForEach-Object { + if (Test-Path $_) { + $md = Get-Content -Raw -Path $_ + $yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md) + $isModulePage = $null -ne $yml.'Module Guid' + + if (-not $isModulePage) { + $MarkdownFiles += $_ + } + } + else { + Write-Error -Message ($LocalizedData.PathNotFound -f $_) + } + } + } + + return $MarkdownFiles +} + function GetMarkdownFilesFromPath { [CmdletBinding()] @@ -1492,6 +1521,15 @@ function GetMarkdownFilesFromPath [switch]$IncludeModulePage ) + if ($IncludeModulePage) + { + $filter = '*.md' + } + else + { + $filter = '*-*.md' + } + $aboutFilePrefixPattern = 'about_*' $MarkdownFiles = @() @@ -1506,16 +1544,7 @@ function GetMarkdownFilesFromPath } elseif (Test-Path -PathType Container $_) { - $MarkdownFiles += Get-ChildItem $_ -File | ForEach-Object { - $md = Get-Content -Raw -Path $_ - $yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md) - $isModulePage = $null -ne $yml.'Module Guid' - - if ($IncludeModulePage -and $isModulePage -or -not $isModulePage -and -not $IncludeModulePage) - { - $_ | Where-Object {$_.BaseName -notlike $aboutFilePrefixPattern} - } - } + $MarkdownFiles += Get-ChildItem $_ -Filter $filter | Where-Object {$_.BaseName -notlike $aboutFilePrefixPattern} } else { diff --git a/test/Pester/PlatyPs.Tests.ps1 b/test/Pester/PlatyPs.Tests.ps1 index 153604d0..235ea720 100644 --- a/test/Pester/PlatyPs.Tests.ps1 +++ b/test/Pester/PlatyPs.Tests.ps1 @@ -723,6 +723,8 @@ Describe 'New-ExternalHelp' { } $file = New-MarkdownHelp -Command 'Test-OrderFunction' -OutputFolder $TestDrive -Force $maml = $file | New-ExternalHelp -OutputPath "$TestDrive\TestOrderFunction.xml" -Force + + $extHelp = New-ExternalHelp -Path "$PSScriptRoot/assets/ModuleWithDash" -OutputPath "$TestDrive\ModuleWithDash" } It "generates right order for syntax" { @@ -739,6 +741,10 @@ Describe 'New-ExternalHelp' { $xml = [xml] (Get-Content (Join-Path $TestDrive 'TestOrderFunction.xml')) $xml.helpItems.namespaceuri | Should Be 'http://msh' } + + It 'checks that external help can be generated for modules with dash in it' { + $extHelp | Should -Exist + } } Describe 'New-ExternalHelp -ErrorLogFile' { @@ -1612,4 +1618,11 @@ Describe 'New-YamlHelp' { It 'throws for OutputFolder that is a file'{ { New-YamlHelp "$root\docs\New-YamlHelp.md" -OutputFolder "$outFolder\yaml\New-YamlHelp.yml" } | Should Throw } + + It 'does not omit # in output type names' { + + New-YamlHelp "$PSScriptRoot\assets\New-YamlHelp.md" -OutputFolder "$TestDrive\yaml" -Force + + Get-Content 'D:\temp\yaml\New-YamlHelp.yml' | Should -Contain '- type: IResult\#System.IO.FileInfo[]' + } } diff --git a/test/Pester/assets/ModuleWithDash/Test-Module.md b/test/Pester/assets/ModuleWithDash/Test-Module.md new file mode 100644 index 00000000..95810fd9 --- /dev/null +++ b/test/Pester/assets/ModuleWithDash/Test-Module.md @@ -0,0 +1,16 @@ +--- +Module Name: Test-Module +Module Guid: ad057547-0b77-49d0-b8dd-9ffd6d44b0be +Download Help Link: {{ Update Download Link }} +Help Version: {{ Please enter version of help manually (X.X.X.X) format }} +Locale: en-US +--- + +# Test-Module Module +## Description +{{ Fill in the Description }} + +## Test-Module Cmdlets +### [Test-ModuleCmdlet](Test-ModuleCmdlet.md) +{{ Fill in the Description }} + diff --git a/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md b/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md new file mode 100644 index 00000000..be9093db --- /dev/null +++ b/test/Pester/assets/ModuleWithDash/Test-ModuleCmdlet.md @@ -0,0 +1,46 @@ +--- +external help file: Test-Module-help.xml +Module Name: Test-Module +online version: +schema: 2.0.0 +title: Test-ModuleCmdlet +--- + +# Test-ModuleCmdlet + +## SYNOPSIS +{{ Fill in the Synopsis }} + +## SYNTAX + +``` +Test-ModuleCmdlet [] +``` + +## DESCRIPTION +{{ Fill in the Description }} + +## EXAMPLES + +### Example 1 +```powershell +PS C:\> {{ Add example code here }} +``` + +{{ Add example description here }} + +## PARAMETERS + +### CommonParameters +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). + +## INPUTS + +### None + +## OUTPUTS + +### System.Object +## NOTES + +## RELATED LINKS diff --git a/test/Pester/assets/New-YamlHelp.md b/test/Pester/assets/New-YamlHelp.md new file mode 100644 index 00000000..b64e0c8d --- /dev/null +++ b/test/Pester/assets/New-YamlHelp.md @@ -0,0 +1,153 @@ +--- +external help file: platyPS-help.xml +Module Name: platyPS +online version: https://github.com/PowerShell/platyPS/blob/master/docs/New-YamlHelp.md +schema: 2.0.0 +--- + +# New-YamlHelp + +## SYNOPSIS +Converts Markdown help into YAML to be read easily by external tools + +## SYNTAX + +``` +New-YamlHelp [-Path] -OutputFolder [-Encoding ] [-Force] [] +``` + +## DESCRIPTION +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. + +## EXAMPLES + +### Example 1: Create YAML files +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This creates one YAML file for each cmdlet so external tools can read the structured data for each cmdlet. + +### Example 2: Create YAML files with specific encoding +``` +PS C:\> New-YamlHelp -Path .\docs -OutputFolder .\out\yaml -Force -Encoding ([System.Text.Encoding]::Unicode) + + Directory: D:\Working\PlatyPS\out\yaml + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +-a---- 6/15/2017 11:13 AM 2337 Get-HelpPreview.yml +-a---- 6/15/2017 11:13 AM 3502 Get-MarkdownMetadata.yml +-a---- 6/15/2017 11:13 AM 4143 New-ExternalHelp.yml +-a---- 6/15/2017 11:13 AM 3082 New-ExternalHelpCab.yml +-a---- 6/15/2017 11:13 AM 2581 New-MarkdownAboutHelp.yml +-a---- 6/15/2017 11:13 AM 12356 New-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 1681 New-YamlHelp.yml +-a---- 6/15/2017 11:13 AM 5053 Update-MarkdownHelp.yml +-a---- 6/15/2017 11:13 AM 4661 Update-MarkdownHelpModule.yml +-a---- 6/15/2017 11:13 AM 3350 Update-MarkdownHelpSchema.yml +``` + +This will both read and write the files in the specified -Encoding. +The -Force parameter will overwrite files that already exist. + +## PARAMETERS + +### -Encoding +Specifies the character encoding for your external help file. +Specify a **System.Text.Encoding** object. +For more information, see [Character Encoding in the .NET Framework](https://msdn.microsoft.com/en-us/library/ms404377.aspx) in the Microsoft Developer Network. +For example, you can control Byte Order Mark (BOM) preferences. +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. + +```yaml +Type: Encoding +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Force +Indicates that this cmdlet overwrites an existing file that has the same name. + +```yaml +Type: SwitchParameter +Parameter Sets: (All) +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### -Path +Specifies an array of paths of markdown files or folders. +This cmdlet creates external help based on these files and folders. + +```yaml +Type: String[] +Parameter Sets: (All) +Aliases: + +Required: True +Position: 1 +Default value: None +Accept pipeline input: True (ByPropertyName, ByValue) +Accept wildcard characters: False +``` + +### -OutputFolder +Specifies the folder to create the YAML files in + +```yaml +Type: String +Parameter Sets: (All) +Aliases: + +Required: True +Position: Named +Default value: None +Accept pipeline input: False +Accept wildcard characters: False +``` + +### CommonParameters +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). + +## INPUTS + +### System.String[] +You can pipe an array of paths to this cmdlet. + +## OUTPUTS + +### IResult#System.IO.FileInfo[] +This cmdlet returns a **FileInfo[]** object for created files. + +## NOTES + +## RELATED LINKS