Skip to content

Commit ffe09c2

Browse files
MariusStorhaugCopilot
MariusStorhaug
and
Copilot
authored
🪲 [Fix]: Fix so files are back to expected structure (#21)
## Description This pull request refactors the `Build-PSModuleDocumentation.ps1` script to consistently use the `$docsOutputFolder` variable instead of `$DocsOutputFolder` or `$moduleDocsFolder`, and improves output formatting for command status messages. These changes help standardize variable usage and enhance script readability and maintainability. Refactoring for variable consistency: * Replaced all instances of `$DocsOutputFolder` and `$moduleDocsFolder` with `$docsOutputFolder` throughout the script to ensure consistent variable usage for documentation output paths. [[1]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L69-R87) [[2]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L102-R106) [[3]](diffhunk://#diff-95b236851bd9052577a2cdf569f08e195e7d6cc424f6cb6d074ccc10b2cb7241L115-R158) Output and formatting improvements: * Updated status message output to use `$PSStyle.Foreground.Green` and `$PSStyle.Foreground.Red` for colored checkmarks and crosses, improving readability of command results. * Added a section to display all generated documentation files after creation, making it easier to verify output. Minor improvements: * Disabled verbose output when importing the module with `Import-Module` by setting `-Verbose:$false`, reducing unnecessary log noise. --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
1 parent 71c21f4 commit ffe09c2

File tree

1 file changed

+22
-21
lines changed

1 file changed

+22
-21
lines changed

‎scripts/helpers/Build-PSModuleDocumentation.ps1‎

Lines changed: 22 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -47,13 +47,12 @@
4747

4848
Write-Host '::group::Build docs - Generate markdown help - Raw'
4949
Install-PSModule -Path $ModuleOutputFolder
50-
$moduleInfo = Import-Module -Name $ModuleName -Force -PassThru
50+
$moduleInfo = Import-Module -Name $ModuleName -PassThru -Verbose:$false -Force
5151

5252
# Get all exported commands from the module
5353
$commands = $moduleInfo.ExportedCommands.Values | Where-Object { $_.CommandType -ne 'Alias' }
5454

55-
Write-Host "Found $($commands.Count) commands to process"
56-
55+
Write-Host "::group::Build docs - Generating markdown help files for $($commands.Count) commands in [$docsOutputFolder]"
5756
foreach ($command in $commands) {
5857
try {
5958
Write-Host "$($command.Name)" -NoNewline
@@ -66,21 +65,24 @@
6665
Force = $true
6766
}
6867
$null = New-MarkdownCommandHelp @params
69-
Write-Host ' - ✓' -ForegroundColor Green
68+
Write-Host " - $($PSStyle.Foreground.Green)✓$($PSStyle.Reset)"
7069
} catch {
71-
Write-Host ' - ✗' -ForegroundColor Red
70+
Write-Host " - $($PSStyle.Foreground.Red)✗$($PSStyle.Reset)"
7271
$_
7372
}
7473
}
7574

76-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
77-
$fileName = $_.Name
78-
Write-Host "::group:: - [$fileName]"
75+
Write-Host '::group::Build docs - Generated files'
76+
Get-ChildItem -Path $docsOutputFolder -Recurse | Select-Object -ExpandProperty FullName
77+
78+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | Sort-Object FullName | ForEach-Object {
79+
$relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $_.FullName)
80+
Write-Host "::group:: - [$relPath]"
7981
Show-FileContent -Path $_
8082
}
8183

8284
Write-Host '::group::Build docs - Fix markdown code blocks'
83-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
85+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
8486
$content = Get-Content -Path $_.FullName
8587
$fixedOpening = $false
8688
$newContent = @()
@@ -99,7 +101,7 @@
99101
}
100102

101103
Write-Host '::group::Build docs - Fix markdown escape characters'
102-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
104+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
103105
$content = Get-Content -Path $_.FullName -Raw
104106
$content = $content -replace '\\`', '`'
105107
$content = $content -replace '\\\[', '['
@@ -112,50 +114,49 @@
112114

113115
Write-Host '::group::Build docs - Structure markdown files to match source files'
114116
$PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item
115-
$moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName
116-
Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
117+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
117118
$file = $_
118-
$relPath = [System.IO.Path]::GetRelativePath($moduleDocsFolder, $file.FullName)
119+
$relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $file.FullName)
119120
Write-Host " - $relPath"
120121
Write-Host " Path: $file"
121122

122123
# find the source code file that matches the markdown file
123124
$scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') }
124125
Write-Host " PS1 path: $scriptPath"
125-
$docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder).Replace('.ps1', '.md')
126+
$docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder).Replace('.ps1', '.md')
126127
Write-Host " MD path: $docsFilePath"
127128
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
128129
$null = New-Item -Path $docsFolderPath -ItemType Directory -Force
129130
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
130131
}
131132

132133
Write-Host '::group::Build docs - Fix frontmatter title'
133-
Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
134+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
134135
$content = Get-Content -Path $_.FullName -Raw
135136
# Replace 'title:' with 'ms.title:' in frontmatter only (between --- markers)
136137
$content = $content -replace '(?s)^(---.*?)title:(.*?---)', '$1ms.title:$2'
137138
$content | Set-Content -Path $_.FullName
138139
}
139140

140-
Write-Host '::group::Build docs - Move markdown files from source files to docs'
141-
$moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName
141+
Write-Host '::group::Build docs - Move markdown files from public functions folder to docs output folder'
142142
Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object {
143143
$file = $_
144144
$relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName)
145145
Write-Host " - $relPath"
146146
Write-Host " Path: $file"
147147

148-
$docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder)
148+
$docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder)
149149
Write-Host " MD path: $docsFilePath"
150150
$docsFolderPath = Split-Path -Path $docsFilePath -Parent
151151
$null = New-Item -Path $docsFolderPath -ItemType Directory -Force
152152
Move-Item -Path $file.FullName -Destination $docsFilePath -Force
153153
}
154+
Write-Host '::endgroup::'
154155

155156
Write-Host '────────────────────────────────────────────────────────────────────────────────'
156-
Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object {
157-
$fileName = $_.Name
158-
Write-Host "::group:: - [$fileName]"
157+
Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | Sort-Object FullName | ForEach-Object {
158+
$relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $_.FullName)
159+
Write-Host "::group:: - [$relPath]"
159160
Show-FileContent -Path $_
160161
}
161162
}

0 commit comments

Comments
 (0)