Fix issues with module name and external help file metadata

src/Markdown.MAML/Model/YAML/YamlInputOutput.cs

@@ -2,7 +2,23 @@
 {
     public class YamlInputOutput
     {
-        public string Type { get; set; }
+        string _type;
+        public string Type
+        {
+            get
+            {
+                if (_type.Contains("#"))
+                {
+                    return _type.Replace("#", "\\#");
+                }
+
+                return _type;
+            }
+            set
+            {
+                _type = value;
+            }
+        }
         public string Description { get; set; }
     }
 }

src/platyPS/platyPS.psm1

@@ -834,7 +834,12 @@ function New-ExternalHelp
 
     process
     {
-        $MarkdownFiles += GetMarkdownFilesFromPath $Path
+        $files = GetMarkdownFilesFromPath $Path
+
+        if ($files)
+        {
+            $MarkdownFiles += FilterMdFileToExcludeModulePage -Path $files
+        }
 
         if($MarkdownFiles)
         {
@@ -1481,6 +1486,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 $_.FullName) {
+                $md = Get-Content -Raw -Path $_.FullName
+                $yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md)
+                $isModulePage = $null -ne $yml.'Module Guid'
+
+                if (-not $isModulePage) {
+                    $MarkdownFiles += $_
+                }
+            }
+            else {
+                Write-Error -Message ($LocalizedData.PathNotFound -f $_.FullName)
+            }
+        }
+    }
+
+    return $MarkdownFiles
+}
+
 function GetMarkdownFilesFromPath
 {
     [CmdletBinding()]
@@ -1503,7 +1537,6 @@ function GetMarkdownFilesFromPath
 
     $aboutFilePrefixPattern = 'about_*'
 
-
     $MarkdownFiles = @()
     if ($Path) {
         $Path | ForEach-Object {

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' {
+
+        $ymlFile = New-YamlHelp "$PSScriptRoot\assets\New-YamlHelp.md" -OutputFolder "$TestDrive\yaml" -Force
+
+        Get-Content $ymlFile | Should -Contain '- type: IResult\#System.IO.FileInfo[]'
+    }
 }

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 }}
+

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 [<CommonParameters>]
+```
+
+## 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

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] <String[]> -OutputFolder <String> [-Encoding <Encoding>] [-Force] [<CommonParameters>]
+```
+
+## 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