PSDocsGenerator.psm1
|
<# .SYNOPSIS Creates an markdown file based on help. .DESCRIPTION Convert PowerShell help information to a markdown file. .PARAMETER ModuleName Specifies the name of the module for which you want to generate the markdown file with documentation. Looks up the specified module name in ``$Env:PSModulePath``. .PARAMETER ModulePath Specifies the path of the module for which you want to generate the markdown file with documentation. This parameter accepts the path to the folder that contains the module. .PARAMETER Destination Specifies the path to where the documentation files are saved. The default is desktop. Wildcards are not allowed. .EXAMPLE Convert-HelpToMarkdown #> function Convert-HelpToMarkdown{ [CmdletBinding(SupportsShouldProcess)] param( [Parameter(ParameterSetName='ModuleName', Position=0, Mandatory=$true)] [System.String]$ModuleName, [Parameter(ParameterSetName='ModulePath', Mandatory=$true)] [System.String]$ModulePath, [System.String]$Destination = "$HOME\Desktop\" ) if($ModulePath){ if($ModulePath -like "*.ps?1"){ $ModulePath = Split-Path $ModulePath -Parent } $ModuleName = (Split-Path $ModulePath -Leaf) Remove-Module -Name $ModuleName -Force -ErrorAction SilentlyContinue Import-Module $ModulePath } else{ Remove-Module -Name $ModuleName -Force -ErrorAction SilentlyContinue Import-Module $ModuleName } $Module = Get-Module $ModuleName $commands = ($Module | select ExportedFunctions).ExportedFunctions $commands = $commands.Keys $commands | ForEach-Object { $help = Get-Help $_ $MDFile = "$Destination\Docs\Modules\$ModuleName\$_.md" $functionName = $_ $content = "# $_`n`n" $content += "## SYNOPSIS`n" $content += "$($help.Synopsis)`n" $content += "`n[\\]: # (END SYNOPSIS)`n`n" $content += "## SYNTAX`n" $content += "```````n" "$((Out-String -InputObject $help.syntax -Width 1000))".Split("`n'") | ForEach-Object { if($_.Length -gt 1){ $content += $_ } } $content += "`n```````n" $content += "`n[\\]: # (END SYNTAX)`n`n" if($help.description.Text){ $content += "## DESCRIPTION`n$($help.description.Text)`n" $content += "`n[\\]: # (END DESCRIPTION)`n`n" } if($help.parameters.parameter){ $content += "## PARAMETERS`n" $help.parameters.parameter | ForEach-Object { $content += "`n### -$($_.name)`n" if("WhatIf" -like ($_.name)){ $content += "Prompts you for confirmation before running the ``$functionName``.`n" } elseif("Confirm" -like ($_.name)){ $content += "Shows what would happen if the ``$functionName`` runs. The cmdlet is not run.`n" } else{ $description = "" $((Out-String -InputObject $_.description).Split("`n") | ForEach-Object {$description+=$_.Trim()}) $content += "$description`n" } $content += "``````yaml`n" $content += "Type: $($_.type.name)`n" $content += "Required: $($_.required)`n" $content += "Position: $($_.position)`n" $content += "Default value: $(if(-not $_.defaultValue){'none'}else{$_.defaultValue.Trim('"')})`n" $content += "Accept pipeline input: $($_.pipelineInput)`n" $content += "Accept wildcard characters: $($_.globbing)`n" $content += "```````n" } if($((Out-String -InputObject $help.syntax) -like "*[<CommonParameters>]*")){ $content += "`n### CommonParameters`n" $content += "This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, [see about_CommonParameters](https://docs.microsoft.com/pl-pl/powershell/module/microsoft.powershell.core/about/about_commonparameters).`n" } $content += "`n[\\]: # (END PARAMETERS)`n`n" } if($commands.Count -gt 1){ $content += "## RELATED LINKS`n" $commands | ForEach-Object { if($functionName -notlike $_){ $content += "[$_]($_.md)`n`n" } } $content += "[\\]: # (END RELATED LINKS)`n`n" } $content += "[\\]: # (Generated by PSDocsGenerator)`n" $content += "[\\]: # (https://github.com/akotu235/PSDocsGenerator)" $content = $content.Split("`n") | ForEach-Object {"$($_.Trim())"} if(-not (Test-Path $MDFile)){ New-Item $MDFile -Force >> $null } Set-Content $MDFile $content -Force } $MDFile = "$Destination\Docs\Modules\$ModuleName\$ModuleName.md" $content = "# $ModuleName Module`n`n" $content += "## Description`n" $content += "$(($Module | select Description).Description)`n" $content += "`n[\\]: # (END DESCRIPTION)`n`n" $content += "## $ModuleName Cmdlets`n`n" $commands | ForEach-Object { $content += "### [$_]($_.md)`n" $content += "$((Get-Help $_).Synopsis)`n`n" } $content += "[\\]: # (END CMDLETS)`n`n" $content += "[\\]: # (Generated by PSDocsGenerator)`n" $content += "[\\]: # (https://github.com/akotu235/PSDocsGenerator)" $content = $content.Split("`n") | ForEach-Object { "$($_.Trim())" } Set-Content $MDFile $content -Force } |