functions/Export-FunctionDocs.ps1
|
function Export-FunctionDocs { <# .SYNOPSIS Exportiert Markdown-Dokumentationen für PowerShell-Funktionen aus einem Quellverzeichnis. .DESCRIPTION Diese Funktion durchsucht rekursiv ein Verzeichnis nach `.ps1`-Dateien, filtert diese mithilfe einer optionalen `exclude-files.json`, lädt die enthaltenen Funktionen via Dot-Sourcing und generiert pro Funktion eine `.md`-Datei mit deren Hilfeinhalt im PlatyPS-Stil. Die Inhalte werden über die Hilfsfunktion `Get-HelpContent` extrahiert. .PARAMETER SourcePath Der Pfad zum Wurzelverzeichnis, das rekursiv nach `.ps1`-Dateien durchsucht wird. .PARAMETER OutputPath Der Zielordner, in dem die `.md`-Dokumentationsdateien gespeichert werden. Wenn der Pfad nicht existiert, wird er erstellt. .EXAMPLE Export-FunctionDocs -SourcePath "C:\Repo\MyModule" -OutputPath "C:\Docs\MyModule" Exportiert alle Funktionen aus `.ps1`-Dateien unter `C:\Repo\MyModule`, ausgenommen jene in der `exclude-files.json`, und speichert `.md`-Dateien nach `C:\Docs\MyModule`. .NOTES Die Ausführung dot-sourct alle `.ps1`-Dateien – Fehlerhafte Dateien führen zu Warnungen. .LINK Get-HelpContent Get-FilteredFiles #> [CmdletBinding()] param ( [Parameter(Mandatory)] [string]$SourcePath, [Parameter(Mandatory)] [string]$OutputPath ) $SourcePath = (Resolve-Path -Path $SourcePath).Path Write-Verbose "Suche nach .ps1-Dateien in $SourcePath" $allPs1Files = Get-ChildItem -Path $SourcePath -Recurse -Filter *.ps1 $filteredFiles = Get-FilteredFiles -Files $allPs1Files -ExcludeListFile (Join-Path -Path $SourcePath -ChildPath 'exclude-files.json') -RootPath $SourcePath if (-not (Test-Path $OutputPath)) { New-Item -Path $OutputPath -ItemType Directory -Force | Out-Null } foreach ($file in $filteredFiles) { Write-Verbose "Analysiere Datei: $($file.FullName)" try { . $file.FullName } catch { Write-Warning "Fehler beim Dot-Sourcing der Datei '$($file.FullName)': $_" continue } $functions = Get-Command -CommandType Function | Where-Object { $_.ScriptBlock.File -eq $file.FullName } foreach ($func in $functions) { $funcName = $func.Name Write-Verbose "Verarbeite Funktion: $funcName" try { $helpContent = Get-HelpContent -FilePath $file.FullName -FunctionName $funcName if (-not $helpContent.SYNOPSIS) { Write-Warning "Funktion '$funcName' hat keine .SYNOPSIS-Dokumentation." continue } $mdPath = Join-Path $OutputPath "$funcName.md" Write-Verbose "Erstelle Dokumentation: $mdPath" $lines = @() $lines += "# $funcName" $lines += "" $lines += "## SYNOPSIS" $lines += $helpContent.SYNOPSIS $lines += "" if ($helpContent.DESCRIPTION) { $lines += "## DESCRIPTION" $lines += $helpContent.DESCRIPTION $lines += "" } if ($helpContent.PARAMETER.Keys.Count -gt 0) { $lines += "## PARAMETERS" foreach ($param in $helpContent.PARAMETER.GetEnumerator()) { $lines += "### -$($param.Key)" $lines += $param.Value -split "`r?`n" | ForEach-Object { " $_" } $lines += "" } } if ($helpContent.EXAMPLE) { $lines += "## EXAMPLES" $lines += ($helpContent.EXAMPLE -split "(?m)^\s*$") | ForEach-Object { '```powershell' $_.Trim() '```' '' } } if ($helpContent.NOTES) { $lines += "## NOTES" $lines += $helpContent.NOTES $lines += "" } if ($helpContent.LINK) { $lines += "## LINKS" $lines += $helpContent.LINK $lines += "" } $lines += "---" $lines += "*Datei: $($file.Name)*" Set-Content -Path $mdPath -Value $lines -Encoding UTF8 } catch { Write-Warning "Fehler beim Verarbeiten von '$funcName': $_" } } } } |