Update-ModifiedCmdletDocs.ps1
|
<# .SYNOPSIS Updates markdown documentation for modified PowerShell cmdlets based on git changes. .DESCRIPTION This script checks git status for modified .ps1 files in the Public directory and automatically updates their corresponding markdown documentation files. .PARAMETER Path The base path to the repository. Defaults to current directory. .PARAMETER DocumentationPath Path to the documentation directory. Defaults to "./Documentation/" .PARAMETER PublicPath Path to the Public cmdlets directory. Defaults to "./Public/" .PARAMETER IncludeStaged Include staged files in addition to unstaged changes. Default is $true. .EXAMPLE .\Update-ModifiedCmdletDocs.ps1 .EXAMPLE .\Update-ModifiedCmdletDocs.ps1 -Path "C:\Projects\Logic.Monitor" #> [CmdletBinding()] param( [string]$Path = ".", [string]$DocumentationPath = "$PSScriptRoot\Documentation\", [string]$PublicPath = "$PSScriptRoot\Public\", [bool]$IncludeStaged = $true, [bool]$RecreateUpdatedDocs = $true ) # Change to the repository directory Push-Location $Path try { # Dynamically find the Dev module file (Dev.*.psd1) $devModule = Get-ChildItem -Path $PSScriptRoot -Filter "Dev.*.psd1" -File | Select-Object -First 1 if (-not $devModule) { throw "No Dev module file (Dev.*.psd1) found in $PSScriptRoot" } Write-Host "Loading module: $($devModule.Name)" -ForegroundColor Cyan Import-Module $devModule.FullName -Force # Extract the production module name (remove "Dev." prefix) $productionModuleName = $devModule.BaseName -replace '^Dev\.', '' Write-Host "Production module name: $productionModuleName" -ForegroundColor Gray } catch { Write-Error "Failed to load Dev module: $_" Pop-Location return } try { Write-Host "Checking for modified PowerShell files..." -ForegroundColor Cyan # Get modified files from git (both staged and unstaged) $gitStatus = if ($IncludeStaged) { git status --porcelain } else { git status --porcelain | Where-Object { $_ -match '^\s*M' } } # Filter for .ps1 files in the Public directory $modifiedCmdlets = $gitStatus | Where-Object { $_ -match "Public/.*\.ps1$" } | ForEach-Object { # Extract filename without path and extension if ($_ -match "Public/([^/]+)\.ps1") { $matches[1] } } | Select-Object -Unique if (-not $modifiedCmdlets) { Write-Host "No modified cmdlet files found in git status." -ForegroundColor Yellow return } Write-Host "Found $($modifiedCmdlets.Count) modified cmdlet(s):" -ForegroundColor Green $modifiedCmdlets | ForEach-Object { Write-Host " - $_" -ForegroundColor Gray } Write-Host "" # Update markdown documentation for each modified cmdlet $successCount = 0 $failCount = 0 $createCount = 0 foreach ($cmdlet in $modifiedCmdlets) { $mdPath = Join-Path $DocumentationPath "$cmdlet.md" if (Test-Path $mdPath) { try { Write-Host "Updating $mdPath..." -ForegroundColor Cyan if ($RecreateUpdatedDocs) { #Delete the existing documentation file Remove-Item $mdPath -ErrorAction SilentlyContinue #Create the new documentation file New-MarkdownHelp -Command $cmdlet -OutputFolder $DocumentationPath -ErrorAction Stop | Out-Null } else { Update-MarkdownHelp -Path $mdPath -Force -ErrorAction Stop | Out-Null } # Fix module name in the generated markdown file $content = Get-Content $mdPath -Raw $content = $content -replace "Module Name: $($devModule.BaseName)", "Module Name: $productionModuleName" Set-Content -Path $mdPath -Value $content -NoNewline Write-Host " ✓ Successfully updated $cmdlet.md" -ForegroundColor Green $successCount++ } catch { Write-Host " ✗ Failed to update $cmdlet.md: $_" -ForegroundColor Red $failCount++ } } else { Write-Host "Creating $mdPath..." -ForegroundColor Cyan Try { New-MarkdownHelp -Command $cmdlet -OutputFolder $DocumentationPath -ErrorAction Stop | Out-Null # Fix module name in the generated markdown file $content = Get-Content $mdPath -Raw $content = $content -replace "Module Name: $($devModule.BaseName)", "Module Name: $productionModuleName" Set-Content -Path $mdPath -Value $content -NoNewline Write-Host " ✓ Successfully created $cmdlet.md" -ForegroundColor Green $createCount++ } catch { Write-Host " ✗ Failed to create $cmdlet.md: $_" -ForegroundColor Red $failCount++ } } } Write-Host "" Write-Host "Summary:" -ForegroundColor Cyan Write-Host " Updated: $successCount" -ForegroundColor Green Write-Host " Created: $createCount" -ForegroundColor Green if ($failCount -gt 0) { Write-Host " Failed/Missing: $failCount" -ForegroundColor Yellow } # Regenerate external help after all documentation updates if ($successCount -gt 0 -or $createCount -gt 0) { Write-Host "" Write-Host "Regenerating external help files..." -ForegroundColor Cyan try { $enUSPath = Join-Path $PSScriptRoot "en-US" New-ExternalHelp -OutputPath $enUSPath -Path $DocumentationPath -Force | Out-Null Write-Host " ✓ Successfully regenerated external help in $enUSPath" -ForegroundColor Green } catch { Write-Host " ✗ Failed to regenerate external help: $_" -ForegroundColor Red } } } catch { Write-Error "An error occurred: $_" } finally { Pop-Location } |