diff --git a/scripts/helpers/Build-PSModuleDocumentation.ps1 b/scripts/helpers/Build-PSModuleDocumentation.ps1 index 4f114d5..1b33e3b 100644 --- a/scripts/helpers/Build-PSModuleDocumentation.ps1 +++ b/scripts/helpers/Build-PSModuleDocumentation.ps1 @@ -47,13 +47,12 @@ Write-Host '::group::Build docs - Generate markdown help - Raw' Install-PSModule -Path $ModuleOutputFolder - $moduleInfo = Import-Module -Name $ModuleName -Force -PassThru + $moduleInfo = Import-Module -Name $ModuleName -PassThru -Verbose:$false -Force # Get all exported commands from the module $commands = $moduleInfo.ExportedCommands.Values | Where-Object { $_.CommandType -ne 'Alias' } - Write-Host "Found $($commands.Count) commands to process" - + Write-Host "::group::Build docs - Generating markdown help files for $($commands.Count) commands in [$docsOutputFolder]" foreach ($command in $commands) { try { Write-Host "$($command.Name)" -NoNewline @@ -66,21 +65,24 @@ Force = $true } $null = New-MarkdownCommandHelp @params - Write-Host ' - ✓' -ForegroundColor Green + Write-Host " - $($PSStyle.Foreground.Green)✓$($PSStyle.Reset)" } catch { - Write-Host ' - ✗' -ForegroundColor Red + Write-Host " - $($PSStyle.Foreground.Red)✗$($PSStyle.Reset)" $_ } } - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { - $fileName = $_.Name - Write-Host "::group:: - [$fileName]" + Write-Host '::group::Build docs - Generated files' + Get-ChildItem -Path $docsOutputFolder -Recurse | Select-Object -ExpandProperty FullName + + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | Sort-Object FullName | ForEach-Object { + $relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $_.FullName) + Write-Host "::group:: - [$relPath]" Show-FileContent -Path $_ } Write-Host '::group::Build docs - Fix markdown code blocks' - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { $content = Get-Content -Path $_.FullName $fixedOpening = $false $newContent = @() @@ -99,7 +101,7 @@ } Write-Host '::group::Build docs - Fix markdown escape characters' - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { $content = Get-Content -Path $_.FullName -Raw $content = $content -replace '\\`', '`' $content = $content -replace '\\\[', '[' @@ -112,17 +114,16 @@ Write-Host '::group::Build docs - Structure markdown files to match source files' $PublicFunctionsFolder = Join-Path $ModuleSourceFolder.FullName 'functions\public' | Get-Item - $moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName - Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object { + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { $file = $_ - $relPath = [System.IO.Path]::GetRelativePath($moduleDocsFolder, $file.FullName) + $relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $file.FullName) Write-Host " - $relPath" Write-Host " Path: $file" # find the source code file that matches the markdown file $scriptPath = Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force | Where-Object { $_.Name -eq ($file.BaseName + '.ps1') } Write-Host " PS1 path: $scriptPath" - $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder).Replace('.ps1', '.md') + $docsFilePath = ($scriptPath.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder).Replace('.ps1', '.md') Write-Host " MD path: $docsFilePath" $docsFolderPath = Split-Path -Path $docsFilePath -Parent $null = New-Item -Path $docsFolderPath -ItemType Directory -Force @@ -130,32 +131,32 @@ } Write-Host '::group::Build docs - Fix frontmatter title' - Get-ChildItem -Path $moduleDocsFolder -Recurse -Force -Include '*.md' | ForEach-Object { + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { $content = Get-Content -Path $_.FullName -Raw # Replace 'title:' with 'ms.title:' in frontmatter only (between --- markers) $content = $content -replace '(?s)^(---.*?)title:(.*?---)', '$1ms.title:$2' $content | Set-Content -Path $_.FullName } - Write-Host '::group::Build docs - Move markdown files from source files to docs' - $moduleDocsFolder = Join-Path $DocsOutputFolder.FullName $ModuleName + Write-Host '::group::Build docs - Move markdown files from public functions folder to docs output folder' Get-ChildItem -Path $PublicFunctionsFolder -Recurse -Force -Include '*.md' | ForEach-Object { $file = $_ $relPath = [System.IO.Path]::GetRelativePath($PublicFunctionsFolder.FullName, $file.FullName) Write-Host " - $relPath" Write-Host " Path: $file" - $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $moduleDocsFolder) + $docsFilePath = ($file.FullName).Replace($PublicFunctionsFolder.FullName, $docsOutputFolder) Write-Host " MD path: $docsFilePath" $docsFolderPath = Split-Path -Path $docsFilePath -Parent $null = New-Item -Path $docsFolderPath -ItemType Directory -Force Move-Item -Path $file.FullName -Destination $docsFilePath -Force } + Write-Host '::endgroup::' Write-Host '────────────────────────────────────────────────────────────────────────────────' - Get-ChildItem -Path $DocsOutputFolder -Recurse -Force -Include '*.md' | ForEach-Object { - $fileName = $_.Name - Write-Host "::group:: - [$fileName]" + Get-ChildItem -Path $docsOutputFolder -Recurse -Force -Include '*.md' | Sort-Object FullName | ForEach-Object { + $relPath = [System.IO.Path]::GetRelativePath($docsOutputFolder, $_.FullName) + Write-Host "::group:: - [$relPath]" Show-FileContent -Path $_ } }