Skip to content

Commit 87bc22e

Browse files
MariusStorhaugMariusStorhaug
committed
Refactor scripts to improve readability and maintainability; add Add-PSModulePath and Show-FileContent functions
1 parent 9fbde31 commit 87bc22e

File tree

8 files changed

+200
-149
lines changed

8 files changed

+200
-149
lines changed

‎.github/workflows/Action-Test.yml‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -25,9 +25,6 @@ jobs:
2525
- name: Checkout repo
2626
uses: actions/checkout@v4
2727

28-
- name: Initialize environment
29-
uses: PSModule/Initialize-PSModule@main
30-
3128
- name: Upload module artifact
3229
uses: actions/upload-artifact@v4
3330
with:

‎scripts/helpers/Add-PSModulePath.ps1‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
function Add-PSModulePath {
2+
<#
3+
.SYNOPSIS
4+
Adds a path to the PSModulePath environment variable.
5+
6+
.DESCRIPTION
7+
Adds a path to the PSModulePath environment variable.
8+
For Linux and macOS, the path delimiter is ':' and for Windows it is ';'.
9+
10+
.EXAMPLE
11+
Add-PSModulePath -Path 'C:\Users\user\Documents\WindowsPowerShell\Modules'
12+
13+
Adds the path 'C:\Users\user\Documents\WindowsPowerShell\Modules' to the PSModulePath environment variable.
14+
#>
15+
[CmdletBinding()]
16+
param(
17+
# Path to the folder where the module source code is located.
18+
[Parameter(Mandatory)]
19+
[string] $Path
20+
)
21+
$PSModulePathSeparator = [System.IO.Path]::PathSeparator
22+
23+
$env:PSModulePath += "$PSModulePathSeparator$Path"
24+
25+
Write-Verbose 'PSModulePath:'
26+
$env:PSModulePath.Split($PSModulePathSeparator) | ForEach-Object {
27+
Write-Verbose " - [$_]"
28+
}
29+
}

‎scripts/helpers/Build-PSModuleDocumentation.ps1‎

Lines changed: 71 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,10 @@
77
Builds a module.
88
#>
99
[CmdletBinding()]
10-
[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
11-
'PSReviewUnusedParameter', '', Scope = 'Function',
12-
Justification = 'LogGroup - Scoping affects the variables line of sight.'
13-
)]
1410
[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
1511
'PSAvoidUsingWriteHost', '', Scope = 'Function',
1612
Justification = 'Want to just write to the console, not the pipeline.'
1713
)]
18-
#Requires -Modules GitHub
19-
#Requires -Modules Utilities
2014
param(
2115
# Name of the module.
2216
[Parameter(Mandatory)]
@@ -35,100 +29,93 @@
3529
[string] $DocsOutputFolderPath
3630
)
3731

38-
LogGroup "Documenting module [$ModuleName]" {
39-
Write-Host "Source path: [$ModuleSourceFolderPath]"
40-
if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
41-
Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
42-
exit 1
43-
}
44-
$moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
45-
Write-Host "Module source folder: [$moduleSourceFolder]"
32+
Write-Host "::group::Documenting module [$ModuleName]"
33+
Write-Host "Source path: [$ModuleSourceFolderPath]"
34+
if (-not (Test-Path -Path $ModuleSourceFolderPath)) {
35+
Write-Error "Source folder not found at [$ModuleSourceFolderPath]"
36+
exit 1
37+
}
38+
$moduleSourceFolder = Get-Item -Path $ModuleSourceFolderPath
39+
Write-Host "Module source folder: [$moduleSourceFolder]"
4640

47-
$moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
48-
Write-Host "Module output folder: [$moduleOutputFolder]"
41+
$moduleOutputFolder = New-Item -Path $ModulesOutputFolderPath -Name $ModuleName -ItemType Directory -Force
42+
Write-Host "Module output folder: [$moduleOutputFolder]"
4943

50-
$docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
51-
Write-Host "Docs output folder: [$docsOutputFolder]"
52-
}
44+
$docsOutputFolder = New-Item -Path $DocsOutputFolderPath -ItemType Directory -Force
45+
Write-Host "Docs output folder: [$docsOutputFolder]"
5346

54-
LogGroup 'Build docs - Generate markdown help' {
55-
Add-PSModulePath -Path (Split-Path -Path $ModuleOutputFolder -Parent)
56-
Import-PSModule -Path $ModuleOutputFolder -ModuleName $ModuleName
57-
Write-Host ($ModuleName | Get-Module)
58-
$null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
59-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
60-
$fileName = $_.Name
61-
LogGroup " - [$fileName]" {
62-
Show-FileContent -Path $_
63-
}
64-
}
47+
Write-Host '::group::Build docs - Generate markdown help'
48+
Add-PSModulePath -Path (Split-Path -Path $ModuleOutputFolder -Parent)
49+
Import-PSModule -Path $ModuleOutputFolder -ModuleName $ModuleName
50+
Write-Host ($ModuleName | Get-Module)
51+
$null = New-MarkdownHelp -Module $ModuleName -OutputFolder $DocsOutputFolder -Force -Verbose
52+
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
53+
$fileName = $_.Name
54+
Write-Host "::group:: - [$fileName]"
55+
Show-FileContent -Path $_
6556
}
6657

67-
LogGroup 'Build docs - Fix markdown code blocks' {
68-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
69-
$content = Get-Content -Path $_.FullName
70-
$fixedOpening = $false
71-
$newContent = @()
72-
foreach ($line in $content) {
73-
if ($line -match '^```$' -and -not $fixedOpening) {
74-
$line = $line -replace '^```$', '```powershell'
75-
$fixedOpening = $true
76-
} elseif ($line -match '^```.+$') {
77-
$fixedOpening = $true
78-
} elseif ($line -match '^```$') {
79-
$fixedOpening = $false
80-
}
81-
$newContent += $line
58+
Write-Host '::group::Build docs - Fix markdown code blocks'
59+
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
60+
$content = Get-Content -Path $_.FullName
61+
$fixedOpening = $false
62+
$newContent = @()
63+
foreach ($line in $content) {
64+
if ($line -match '^```$' -and -not $fixedOpening) {
65+
$line = $line -replace '^```$', '```powershell'
66+
$fixedOpening = $true
67+
} elseif ($line -match '^```.+$') {
68+
$fixedOpening = $true
69+
} elseif ($line -match '^```$') {
70+
$fixedOpening = $false
8271
}
83-
$newContent | Set-Content -Path $_.FullName
72+
$newContent += $line
8473
}
74+
$newContent | Set-Content -Path $_.FullName
8575
}
8676

87-
LogGroup 'Build docs - Fix markdown escape characters' {
88-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
89-
$content = Get-Content -Path $_.FullName -Raw
90-
$content = $content -replace '\\`', '`'
91-
$content = $content -replace '\\\[', '['
92-
$content = $content -replace '\\\]', ']'
93-
$content = $content -replace '\\\<', '<'
94-
$content = $content -replace '\\\>', '>'
95-
$content = $content -replace '\\\\', '\'
96-
$content | Set-Content -Path $_.FullName
97-
}
77+
Write-Host '::group::Build docs - Fix markdown escape characters'
78+
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
79+
$content = Get-Content -Path $_.FullName -Raw
80+
$content = $content -replace '\\`', '`'
81+
$content = $content -replace '\\\[', '['
82+
$content = $content -replace '\\\]', ']'
83+
$content = $content -replace '\\\<', '<'
84+
$content = $content -replace '\\\>', '>'
85+
$content = $content -replace '\\\\', '\'
86+
$content | Set-Content -Path $_.FullName
9887
}
9988

100-
LogGroup 'Build docs - Structure markdown files to match source files' {
101-
$PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
102-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
103-
$file = $_
104-
Write-Host "Processing: $file"
89+
Write-Host '::group::Build docs - Structure markdown files to match source files'
90+
$PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
91+
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
92+
$file = $_
93+
Write-Host "Processing: $file"
10594

106-
# find the source code file that matches the markdown file
107-
$scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
108-
Write-Host "Found script path: $scriptPath"
109-
$docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
110-
Write-Host "Doc file path: $docsFilePath"
111-
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
112-
New-Item -Path $docsFolderPath -ItemType Directory -Force
113-
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
114-
}
115-
# Get the MD files that are in the public functions folder and move them to the same place in the docs folder
116-
Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
117-
$file = $_
118-
Write-Host "Processing: $file"
119-
$docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
120-
Write-Host "Doc file path: $docsFilePath"
121-
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
122-
New-Item -Path $docsFolderPath -ItemType Directory -Force
123-
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
124-
}
95+
# find the source code file that matches the markdown file
96+
$scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
97+
Write-Host "Found script path: $scriptPath"
98+
$docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName).Replace('.ps1', '.md')
99+
Write-Host "Doc file path: $docsFilePath"
100+
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
101+
New-Item -Path $docsFolderPath -ItemType Directory -Force
102+
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
103+
}
104+
# Get the MD files that are in the public functions folder and move them to the same place in the docs folder
105+
Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
106+
$file = $_
107+
Write-Host "Processing: $file"
108+
$docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $DocsOutputFolder.FullName)
109+
Write-Host "Doc file path: $docsFilePath"
110+
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
111+
New-Item -Path $docsFolderPath -ItemType Directory -Force
112+
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
125113
}
126114

127115
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
128116
$fileName = $_.Name
129117
$hash = (Get-FileHash -Path $_.FullName -Algorithm SHA256).Hash
130-
LogGroup " - [$fileName] - [$hash]" {
131-
Show-FileContent -Path $_
132-
}
118+
Write-Host "::group:: - [$fileName] - [$hash]"
119+
Show-FileContent -Path $_
133120
}
134121
}

‎scripts/helpers/Import-PSModule.ps1‎

Lines changed: 16 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -7,43 +7,41 @@
77
Imports a build PS module.
88
99
.EXAMPLE
10-
Import-PSModule -SourceFolderPath $ModuleFolderPath -ModuleName $ModuleName
10+
Import-PSModule -SourceFolderPath $ModuleFolderPath -ModuleName $moduleName
1111
12-
Imports a module located at $ModuleFolderPath with the name $ModuleName.
12+
Imports a module located at $ModuleFolderPath with the name $moduleName.
1313
#>
1414
[CmdletBinding()]
15-
#Requires -Modules Utilities
1615
[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
1716
'PSAvoidUsingWriteHost', '', Scope = 'Function',
1817
Justification = 'Want to just write to the console, not the pipeline.'
1918
)]
2019
param(
2120
# Path to the folder where the module source code is located.
2221
[Parameter(Mandatory)]
23-
[string] $Path,
24-
25-
# Name of the module.
26-
[Parameter(Mandatory)]
27-
[string] $ModuleName
22+
[string] $Path
2823
)
2924

3025
$moduleName = Split-Path -Path $Path -Leaf
31-
$manifestFileName = "$moduleName.psd1"
32-
$manifestFilePath = Join-Path -Path $Path $manifestFileName
33-
$manifestFile = Get-ModuleManifest -Path $manifestFilePath -As FileInfo -Verbose
26+
$manifestFilePath = Join-Path -Path $Path "$moduleName.psd1"
27+
28+
Write-Host " - Manifest file path: [$manifestFilePath]"
29+
Remove-PSModule -Name $moduleName
30+
Resolve-PSModuleDependency -ManifestFilePath $manifestFilePath
31+
32+
Write-Host ' - List installed modules'
33+
Get-InstalledPSResource | Format-Table -AutoSize
3434

35-
Write-Host "Manifest file path: [$($manifestFile.FullName)]" -Verbose
36-
Remove-PSModule -Name $ModuleName
37-
Resolve-PSModuleDependency -ManifestFilePath $manifestFile
38-
Import-Module -Name $ModuleName -RequiredVersion '999.0.0'
35+
Write-Host " - Importing module [$moduleName] v999"
36+
Import-Module -Name $moduleName -RequiredVersion '999.0.0'
3937

40-
Write-Host 'List loaded modules'
38+
Write-Host ' - List loaded modules'
4139
$availableModules = Get-Module -ListAvailable -Refresh -Verbose:$false
4240
$availableModules | Select-Object Name, Version, Path | Sort-Object Name | Format-Table -AutoSize
43-
Write-Host 'List commands'
41+
Write-Host ' - List commands'
4442
Write-Host (Get-Command -Module $moduleName -ListImported | Format-Table -AutoSize | Out-String)
4543

46-
if ($ModuleName -notin $availableModules.Name) {
44+
if ($moduleName -notin $availableModules.Name) {
4745
throw 'Module not found'
4846
}
4947
}

‎scripts/helpers/Remove-PSModule.ps1‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,6 @@
33
.SYNOPSIS
44
Removes and uninstalls a PowerShell module.
55
6-
76
.EXAMPLE
87
Remove-PSModule -ModuleName 'Utilities'
98

‎scripts/helpers/Resolve-PSModuleDependency.ps1‎

Lines changed: 35 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,26 @@
11
function Resolve-PSModuleDependency {
22
<#
3-
.SYNOPSIS
4-
Resolve dependencies for a module based on the manifest file.
3+
.SYNOPSIS
4+
Resolve dependencies for a module based on the manifest file.
55
6-
.DESCRIPTION
7-
Resolve dependencies for a module based on the manifest file, following PSModuleInfo structure
6+
.DESCRIPTION
7+
Resolve dependencies for a module based on the manifest file, following PSModuleInfo structure
88
9-
.EXAMPLE
10-
Resolve-PSModuleDependency -Path 'C:\MyModule\MyModule.psd1'
9+
.EXAMPLE
10+
Resolve-PSModuleDependency -Path 'C:\MyModule\MyModule.psd1'
1111
12-
Installs all modules defined in the manifest file, following PSModuleInfo structure.
12+
Installs all modules defined in the manifest file, following PSModuleInfo structure.
1313
14-
.NOTES
15-
Should later be adapted to support both pre-reqs, and dependencies.
16-
Should later be adapted to take 4 parameters sets: specific version ("requiredVersion" | "GUID"), latest version ModuleVersion,
17-
and latest version within a range MinimumVersion - MaximumVersion.
14+
.NOTES
15+
Should later be adapted to support both pre-reqs, and dependencies.
16+
Should later be adapted to take 4 parameters sets: specific version ("requiredVersion" | "GUID"), latest version ModuleVersion,
17+
and latest version within a range MinimumVersion - MaximumVersion.
1818
#>
19-
[Alias('Resolve-PSModuleDependencies')]
20-
[CmdletBinding()]
21-
#Requires -Modules Retry
2219
[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
2320
'PSAvoidUsingWriteHost', '', Scope = 'Function',
2421
Justification = 'Want to just write to the console, not the pipeline.'
2522
)]
23+
[CmdletBinding()]
2624
param(
2725
# The path to the manifest file.
2826
[Parameter(Mandatory)]
@@ -32,8 +30,8 @@
3230
Write-Host 'Resolving dependencies'
3331

3432
$manifest = Import-PowerShellDataFile -Path $ManifestFilePath
35-
Write-Host "Reading [$ManifestFilePath]"
36-
Write-Host "Found [$($manifest.RequiredModules.Count)] modules to install"
33+
Write-Host " - Reading [$ManifestFilePath]"
34+
Write-Host " - Found [$($manifest.RequiredModules.Count)] modules to install"
3735

3836
foreach ($requiredModule in $manifest.RequiredModules) {
3937
$installParams = @{}
@@ -51,19 +49,33 @@
5149

5250
$VerbosePreferenceOriginal = $VerbosePreference
5351
$VerbosePreference = 'SilentlyContinue'
54-
Write-Host "[$($installParams.Name)] - Uninstalling module"
52+
Write-Host " - [$($installParams.Name)] - Uninstalling module"
5553
Remove-PSModule -Name $installParams.Name
56-
Write-Host "[$($installParams.Name)] - Installing module"
57-
Retry -Count 5 -Delay 10 {
58-
Install-Module @installParams -AllowPrerelease:$false
54+
Write-Host " - [$($installParams.Name)] - Installing module"
55+
$Count = 5
56+
$Delay = 10
57+
for ($i = 0; $i -lt $Count; $i++) {
58+
try {
59+
Install-Module @installParams
60+
break
61+
} catch {
62+
Write-Warning 'The command:'
63+
Write-Warning $Run.ToString()
64+
Write-Warning "failed with error: $_"
65+
if ($i -eq $Count - 1) {
66+
throw
67+
}
68+
Write-Warning "Retrying in $Delay seconds..."
69+
Start-Sleep -Seconds $Delay
70+
}
5971
}
6072
$VerbosePreference = $VerbosePreferenceOriginal
61-
Write-Host "[$($installParams.Name)] - Importing module"
73+
Write-Host " - [$($installParams.Name)] - Importing module"
6274
$VerbosePreferenceOriginal = $VerbosePreference
6375
$VerbosePreference = 'SilentlyContinue'
6476
Import-Module @installParams
6577
$VerbosePreference = $VerbosePreferenceOriginal
66-
Write-Host "[$($installParams.Name)] - Done"
78+
Write-Host " - [$($installParams.Name)] - Done"
6779
}
68-
Write-Host 'Resolving dependencies - Done'
80+
Write-Host ' - Resolving dependencies - Done'
6981
}

0 commit comments

Comments
 (0)