Skip to content

Commit 7da4751

Browse files
adityapatwardhanadityapatwardhan
authored
Fix issues with module name and external help file metadata (#542)
1 parent 614b419 commit 7da4751

File tree

8 files changed

+444
-4
lines changed

8 files changed

+444
-4
lines changed

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

+17-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,23 @@
22
{
33
public class YamlInputOutput
44
{
5-
public string Type { get; set; }
5+
string _type;
6+
public string Type
7+
{
8+
get
9+
{
10+
if (_type.Contains("#"))
11+
{
12+
return _type.Replace("#", "\\#");
13+
}
14+
15+
return _type;
16+
}
17+
set
18+
{
19+
_type = value;
20+
}
21+
}
622
public string Description { get; set; }
723
}
824
}

‎src/platyPS/platyPS.psm1

+48-3
Original file line numberDiff line numberDiff line change
@@ -834,7 +834,12 @@ function New-ExternalHelp
834834

835835
process
836836
{
837-
$MarkdownFiles += GetMarkdownFilesFromPath $Path
837+
$files = GetMarkdownFilesFromPath $Path
838+
839+
if ($files)
840+
{
841+
$MarkdownFiles += FilterMdFileToExcludeModulePage -Path $files
842+
}
838843

839844
if($MarkdownFiles)
840845
{
@@ -1481,6 +1486,35 @@ function GetAboutTopicsFromPath
14811486
return $AboutMarkDownFiles
14821487
}
14831488

1489+
function FilterMdFileToExcludeModulePage {
1490+
[CmdletBinding()]
1491+
param(
1492+
[Parameter(Mandatory = $true)]
1493+
[System.IO.FileInfo[]]$Path
1494+
)
1495+
1496+
$MarkdownFiles = @()
1497+
1498+
if ($Path) {
1499+
$Path | ForEach-Object {
1500+
if (Test-Path $_.FullName) {
1501+
$md = Get-Content -Raw -Path $_.FullName
1502+
$yml = [Markdown.MAML.Parser.MarkdownParser]::GetYamlMetadata($md)
1503+
$isModulePage = $null -ne $yml.'Module Guid'
1504+
1505+
if (-not $isModulePage) {
1506+
$MarkdownFiles += $_
1507+
}
1508+
}
1509+
else {
1510+
Write-Error -Message ($LocalizedData.PathNotFound -f $_.FullName)
1511+
}
1512+
}
1513+
}
1514+
1515+
return $MarkdownFiles
1516+
}
1517+
14841518
function GetMarkdownFilesFromPath
14851519
{
14861520
[CmdletBinding()]
@@ -1503,7 +1537,6 @@ function GetMarkdownFilesFromPath
15031537

15041538
$aboutFilePrefixPattern = 'about_*'
15051539

1506-
15071540
$MarkdownFiles = @()
15081541
if ($Path) {
15091542
$Path | ForEach-Object {
@@ -1830,6 +1863,13 @@ function GetHelpFileName
18301863
Where-Object {$_.ModuleType -ne 'Manifest'} |
18311864
Where-Object {$_.ExportedCommands.Keys -contains $CommandInfo.Name}
18321865

1866+
$nestedModules = @(
1867+
($CommandInfo.Module.NestedModules) |
1868+
Where-Object { $_.ModuleType -ne 'Manifest' } |
1869+
Where-Object { $_.ExportedCommands.Keys -contains $CommandInfo.Name } |
1870+
Select-Object -ExpandProperty Path
1871+
)
1872+
18331873
if (-not $module)
18341874
{
18351875
Write-Warning -Message ($LocalizedData.ModuleNotFoundFromCommand -f '[GetHelpFileName]', $CommandInfo.Name)
@@ -1846,7 +1886,12 @@ function GetHelpFileName
18461886
{
18471887
# for regular modules, we can deduct the filename from the module path file
18481888
$moduleItem = Get-Item -Path $module.Path
1849-
if ($moduleItem.Extension -eq '.psm1') {
1889+
1890+
$isModuleItemNestedModule =
1891+
$null -ne ($nestedModules | Where-Object { $_ -eq $module.Path }) -and
1892+
$CommandInfo.ModuleName -ne $module.Name
1893+
1894+
if ($moduleItem.Extension -eq '.psm1' -and -not $isModuleItemNestedModule) {
18501895
$fileName = $moduleItem.BaseName
18511896
} else {
18521897
$fileName = $moduleItem.Name

‎test/Pester/PlatyPs.Tests.ps1

+25
Original file line numberDiff line numberDiff line change
@@ -705,6 +705,18 @@ Get-Alpha [-WhatIf] [[-CCC] <String>] [[-ddd] <Int32>] [<CommonParameters>]
705705
$help.parameters.parameter | Where-Object { $_.Name -eq 'NameNoWildCard' } | ForEach-Object { $_.globbing -eq 'false'}
706706
}
707707
}
708+
709+
Context 'External help file metadata' {
710+
BeforeAll {
711+
Import-Module "$PSScriptRoot/assets/NestedMod" -Force
712+
$nestedMd = New-MarkdownHelp -Module "NestedMod" -OutputFolder "$TestDrive\NestedMod"
713+
}
714+
715+
It 'checks the external help file metadata is correct for nested module' {
716+
$m = Get-MarkdownMetadata -Path $nestedMd
717+
$m['external help file'] | Should -BeExactly 'Nest.psm1-help.xml'
718+
}
719+
}
708720
}
709721
}
710722

@@ -723,6 +735,8 @@ Describe 'New-ExternalHelp' {
723735
}
724736
$file = New-MarkdownHelp -Command 'Test-OrderFunction' -OutputFolder $TestDrive -Force
725737
$maml = $file | New-ExternalHelp -OutputPath "$TestDrive\TestOrderFunction.xml" -Force
738+
739+
$extHelp = New-ExternalHelp -Path "$PSScriptRoot/assets/ModuleWithDash" -OutputPath "$TestDrive\ModuleWithDash"
726740
}
727741

728742
It "generates right order for syntax" {
@@ -739,6 +753,10 @@ Describe 'New-ExternalHelp' {
739753
$xml = [xml] (Get-Content (Join-Path $TestDrive 'TestOrderFunction.xml'))
740754
$xml.helpItems.namespaceuri | Should Be 'http://msh'
741755
}
756+
757+
It 'checks that external help can be generated for modules with dash in it' {
758+
$extHelp | Should -Exist
759+
}
742760
}
743761

744762
Describe 'New-ExternalHelp -ErrorLogFile' {
@@ -1612,4 +1630,11 @@ Describe 'New-YamlHelp' {
16121630
It 'throws for OutputFolder that is a file'{
16131631
{ New-YamlHelp "$root\docs\New-YamlHelp.md" -OutputFolder "$outFolder\yaml\New-YamlHelp.yml" } | Should Throw
16141632
}
1633+
1634+
It 'does not omit # in output type names' {
1635+
1636+
$ymlFile = New-YamlHelp "$PSScriptRoot\assets\New-YamlHelp.md" -OutputFolder "$TestDrive\yaml" -Force
1637+
1638+
Get-Content $ymlFile | Should -Contain '- type: IResult\#System.IO.FileInfo[]'
1639+
}
16151640
}

‎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/NestedMod/Nest.psm1

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
function Get-Nest
2+
{
3+
[CmdletBinding()]
4+
param(
5+
[Parameter()] [string] $str
6+
)
7+
}

‎test/Pester/assets/NestedMod/NestedMod.psd1

+132
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,132 @@
1+
#
2+
# Module manifest for module 'NestedMod'
3+
#
4+
# Generated by: adity
5+
#
6+
# Generated on: 6/28/2021
7+
#
8+
9+
@{
10+
11+
# Script module or binary module file associated with this manifest.
12+
# RootModule = ''
13+
14+
# Version number of this module.
15+
ModuleVersion = '0.0.1'
16+
17+
# Supported PSEditions
18+
# CompatiblePSEditions = @()
19+
20+
# ID used to uniquely identify this module
21+
GUID = '5aeb9dc7-b9f0-4bf2-8eb5-13663c1bd458'
22+
23+
# Author of this module
24+
Author = 'adity'
25+
26+
# Company or vendor of this module
27+
CompanyName = 'Unknown'
28+
29+
# Copyright statement for this module
30+
Copyright = '(c) adity. All rights reserved.'
31+
32+
# Description of the functionality provided by this module
33+
# Description = ''
34+
35+
# Minimum version of the PowerShell engine required by this module
36+
# PowerShellVersion = ''
37+
38+
# Name of the PowerShell host required by this module
39+
# PowerShellHostName = ''
40+
41+
# Minimum version of the PowerShell host required by this module
42+
# PowerShellHostVersion = ''
43+
44+
# Minimum version of Microsoft .NET Framework required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
45+
# DotNetFrameworkVersion = ''
46+
47+
# Minimum version of the common language runtime (CLR) required by this module. This prerequisite is valid for the PowerShell Desktop edition only.
48+
# ClrVersion = ''
49+
50+
# Processor architecture (None, X86, Amd64) required by this module
51+
# ProcessorArchitecture = ''
52+
53+
# Modules that must be imported into the global environment prior to importing this module
54+
# RequiredModules = @()
55+
56+
# Assemblies that must be loaded prior to importing this module
57+
# RequiredAssemblies = @()
58+
59+
# Script files (.ps1) that are run in the caller's environment prior to importing this module.
60+
# ScriptsToProcess = @()
61+
62+
# Type files (.ps1xml) to be loaded when importing this module
63+
# TypesToProcess = @()
64+
65+
# Format files (.ps1xml) to be loaded when importing this module
66+
# FormatsToProcess = @()
67+
68+
# Modules to import as nested modules of the module specified in RootModule/ModuleToProcess
69+
NestedModules = @('Nest.psm1')
70+
71+
# 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.
72+
FunctionsToExport = 'Get-Nest'
73+
74+
# 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.
75+
CmdletsToExport = '*'
76+
77+
# Variables to export from this module
78+
VariablesToExport = '*'
79+
80+
# 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.
81+
AliasesToExport = '*'
82+
83+
# DSC resources to export from this module
84+
# DscResourcesToExport = @()
85+
86+
# List of all modules packaged with this module
87+
# ModuleList = @()
88+
89+
# List of all files packaged with this module
90+
# FileList = @()
91+
92+
# 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.
93+
PrivateData = @{
94+
95+
PSData = @{
96+
97+
# Tags applied to this module. These help with module discovery in online galleries.
98+
# Tags = @()
99+
100+
# A URL to the license for this module.
101+
# LicenseUri = ''
102+
103+
# A URL to the main website for this project.
104+
# ProjectUri = ''
105+
106+
# A URL to an icon representing this module.
107+
# IconUri = ''
108+
109+
# ReleaseNotes of this module
110+
# ReleaseNotes = ''
111+
112+
# Prerelease string of this module
113+
# Prerelease = ''
114+
115+
# Flag to indicate whether the module requires explicit user acceptance for install/update/save
116+
# RequireLicenseAcceptance = $false
117+
118+
# External dependent modules of this module
119+
# ExternalModuleDependencies = @()
120+
121+
} # End of PSData hashtable
122+
123+
} # End of PrivateData hashtable
124+
125+
# HelpInfo URI of this module
126+
# HelpInfoURI = ''
127+
128+
# Default prefix for commands exported from this module. Override the default prefix using Import-Module -Prefix.
129+
# DefaultCommandPrefix = ''
130+
131+
}
132+

0 commit comments

Comments
 (0)