Fix issues with module name and external help file metadata (#542)

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 {
@@ -1830,6 +1863,13 @@ function GetHelpFileName
                 Where-Object {$_.ModuleType -ne 'Manifest'} |
                 Where-Object {$_.ExportedCommands.Keys -contains $CommandInfo.Name}
 
+            $nestedModules = @(
+                ($CommandInfo.Module.NestedModules) |
+                Where-Object { $_.ModuleType -ne 'Manifest' } |
+                Where-Object { $_.ExportedCommands.Keys -contains $CommandInfo.Name } |
+                Select-Object -ExpandProperty Path
+            )
+
             if (-not $module)
             {
                 Write-Warning -Message ($LocalizedData.ModuleNotFoundFromCommand -f '[GetHelpFileName]', $CommandInfo.Name)
@@ -1846,7 +1886,12 @@ function GetHelpFileName
             {
                 # for regular modules, we can deduct the filename from the module path file
                 $moduleItem = Get-Item -Path $module.Path
-                if ($moduleItem.Extension -eq '.psm1') {
+
+                $isModuleItemNestedModule =
+                    $null -ne ($nestedModules | Where-Object { $_ -eq $module.Path }) -and
+                    $CommandInfo.ModuleName -ne $module.Name
+
+                if ($moduleItem.Extension -eq '.psm1' -and -not $isModuleItemNestedModule) {
                     $fileName = $moduleItem.BaseName
                 } else {
                     $fileName = $moduleItem.Name

test/Pester/PlatyPs.Tests.ps1

@@ -705,6 +705,18 @@ Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>] [<CommonParameters>]
                 $help.parameters.parameter | Where-Object { $_.Name -eq 'NameNoWildCard' } | ForEach-Object { $_.globbing -eq 'false'}
             }
         }
+
+        Context 'External help file metadata' {
+            BeforeAll {
+                Import-Module "$PSScriptRoot/assets/NestedMod" -Force
+                $nestedMd = New-MarkdownHelp -Module "NestedMod" -OutputFolder "$TestDrive\NestedMod"
+            }
+
+            It 'checks the external help file metadata is correct for nested module' {
+                $m = Get-MarkdownMetadata -Path $nestedMd
+                $m['external help file'] | Should -BeExactly 'Nest.psm1-help.xml'
+            }
+        }
     }
 }
 
@@ -723,6 +735,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 +753,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 +1630,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/NestedMod/Nest.psm1

@@ -0,0 +1,7 @@
+function Get-Nest
+{
+    [CmdletBinding()]
+    param(
+	[Parameter()] [string] $str
+	)
+}

test/Pester/assets/NestedMod/NestedMod.psd1

@@ -0,0 +1,132 @@
+#
+# Module manifest for module 'NestedMod'
+#
+# Generated by: adity
+#
+# Generated on: 6/28/2021
+#
+
+@{
+
+# Script module or binary module file associated with this manifest.
+# RootModule = ''
+
+# Version number of this module.
+ModuleVersion = '0.0.1'
+
+# Supported PSEditions
+# CompatiblePSEditions = @()
+
+# ID used to uniquely identify this module
+GUID = '5aeb9dc7-b9f0-4bf2-8eb5-13663c1bd458'
+
+# Author of this module
+Author = 'adity'
+
+# Company or vendor of this module
+CompanyName = 'Unknown'
+
+# Copyright statement for this module
+Copyright = '(c) adity. All rights reserved.'
+
+# Description of the functionality provided by this module
+# Description = ''
+
+# Minimum version of the PowerShell engine required by this module
+# PowerShellVersion = ''
+
+# Name of the PowerShell host required by this module
+# PowerShellHostName = ''
+
+# Minimum version of the PowerShell host required by this module
+# PowerShellHostVersion = ''
+
+# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+# DotNetFrameworkVersion = ''
+
+# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
+# ClrVersion = ''
+
+# Processor architecture (None, X86, Amd64) required by this module
+# ProcessorArchitecture = ''
+
+# Modules that must be imported into the global environment prior to importing this module
+# RequiredModules = @()
+
+# Assemblies that must be loaded prior to importing this module
+# RequiredAssemblies = @()
+
+# Script files (.ps1) that are run in the caller's environment prior to importing this module.
+# ScriptsToProcess = @()
+
+# Type files (.ps1xml) to be loaded when importing this module
+# TypesToProcess = @()
+
+# Format files (.ps1xml) to be loaded when importing this module
+# FormatsToProcess = @()
+
+# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
+NestedModules = @('Nest.psm1')
+
+# Functions to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no functions to export.
+FunctionsToExport = 'Get-Nest'
+
+# Cmdlets to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no cmdlets to export.
+CmdletsToExport = '*'
+
+# Variables to export from this module
+VariablesToExport = '*'
+
+# Aliases to export from this module, for best performance, do not use wildcards and do not delete the entry, use an empty array if there are no aliases to export.
+AliasesToExport = '*'
+
+# DSC resources to export from this module
+# DscResourcesToExport = @()
+
+# List of all modules packaged with this module
+# ModuleList = @()
+
+# List of all files packaged with this module
+# FileList = @()
+
+# Private data to pass to the module specified in RootModule/ModuleToProcess. This may also contain a PSData hashtable with additional module metadata used by PowerShell.
+PrivateData = @{
+
+    PSData = @{
+
+        # Tags applied to this module. These help with module discovery in online galleries.
+        # Tags = @()
+
+        # A URL to the license for this module.
+        # LicenseUri = ''
+
+        # A URL to the main website for this project.
+        # ProjectUri = ''
+
+        # A URL to an icon representing this module.
+        # IconUri = ''
+
+        # ReleaseNotes of this module
+        # ReleaseNotes = ''
+
+        # Prerelease string of this module
+        # Prerelease = ''
+
+        # Flag to indicate whether the module requires explicit user acceptance for install/update/save
+        # RequireLicenseAcceptance = $false
+
+        # External dependent modules of this module
+        # ExternalModuleDependencies = @()
+
+    } # End of PSData hashtable
+
+} # End of PrivateData hashtable
+
+# HelpInfo URI of this module
+# HelpInfoURI = ''
+
+# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
+# DefaultCommandPrefix = ''
+
+}
+