diff --git a/.github/workflows/TestReleaseAndPublish.yml b/.github/workflows/TestReleaseAndPublish.yml index 41029f27..a70eff9e 100644 --- a/.github/workflows/TestReleaseAndPublish.yml +++ b/.github/workflows/TestReleaseAndPublish.yml @@ -590,4 +590,9 @@ jobs: if: ${{github.ref_name != 'master'}} uses: ./ id: HelpOutBranch - + - name: PSA + uses: StartAutomating/PSA@main + id: PSA +env: + AT_PROTOCOL_APP_PASSWORD: ${{ secrets.AT_PROTOCOL_APP_PASSWORD }} + AT_PROTOCOL_HANDLE: mrpowershell.bsky.social diff --git a/Assets/HelpOut.svg b/Assets/HelpOut.svg index 2cdd4813..737be7de 100644 --- a/Assets/HelpOut.svg +++ b/Assets/HelpOut.svg @@ -1,4 +1,5 @@ + diff --git a/CHANGELOG.md b/CHANGELOG.md index 5575d1ea..0f6f21f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,20 @@ +### HelpOut 0.4.8: + +* Markdown Help Improvements: + * Fixing Long Examples (Fixes #141) + * Allowing first comment lines in an example to be markdown (#143) + * Also, switching numbered example headings to blockquotes +* Save-MarkdownHelp updates: + * Fixing Piping Behavior (#140) + * Not Saving to illegal windows paths (#132) +* Improving Extended Types Doc Generation + * Now puts extended type documentation into subfolders (#135) + * Also, generates a summary file for each type (#133) +* Updating links to Microsoft modules (#142) +* Integrating PSA into HelpOut (#144) + +--- + ### HelpOut 0.4.7: * Get-MarkdownHelp: Automatically renaming help about aliases (Fixes #130) diff --git a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 index 2f82d0c8..da37256a 100644 --- a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 +++ b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 @@ -31,15 +31,16 @@ $extendedTypeNames = # and be ready to replace most punctuation $replaceMostPunctuation = '[\p{P}-[\-\._]]' +$punctuationNotDashOrUnderscore = '[\p{P}-[\-_]]' # go over each extended type foreach ($extendedType in $extendedTypeNames) { # and get the actual type data - $actualTypeData = Get-TypeData -TypeName $extendedType - foreach ($member in $actualTypeData.Members.Values) { - # If the script looks like it does not have inline help, continue - + $actualTypeData = Get-TypeData -TypeName $extendedType + $memberFiles = + @(foreach ($member in $actualTypeData.Members.Values) { foreach ($potentialProperty in 'Script','GetScriptBlock','SetScriptBlock') { + # If the script looks like it does not have inline help, continue if ($member.$PotentialProperty -notlike '*<#*.synopsis*#>*') { continue } $markdownSplat = @{} # Create a temporary function to hold the help. @@ -53,6 +54,7 @@ foreach ($extendedType in $extendedTypeNames) { elseif ($potentialProperty -eq 'Script') { '' } + $fullExtendedTypeInfo = "$($extendedType).$GetSetNothing$($member.Name)" $temporaryFunctionName = "$($extendedType).$GetSetNothing$($member.Name)" -replace $replaceMostPunctuation $markdownSplat.Rename = "$temporaryFunctionName()" $ExecutionContext.SessionState.PSVariable.Set("function:$($temporaryFunctionName)", $member.$PotentialProperty) @@ -63,12 +65,57 @@ foreach ($extendedType in $extendedTypeNames) { continue } $markdownHelp.HideSection("Syntax") + + $etsDocPath = Join-Path $outputPath "$( + @($fullExtendedTypeInfo -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar + ).md" + # .Save it, - $markdownHelp.Save((Join-Path $outputPath "$($temporaryFunctionName).md")) + $markdownHelp.Save($etsDocPath) # and remove the temporary function (it would have gone out of scope anyways) $ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)") } + }) + + $ExtendedTypeDocFile = Join-Path $outputPath "$( + ($extendedType -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar + )$([IO.Path]::DirectorySeparatorChar)README.md" + + $getSetFile = '\.(?>get|set)_' + $ExtendedTypeDocContent = @( + "## $extendedType" + [Environment]::NewLine + + if ($actualTypeData.Members -and $actualTypeData.Members["README"].Value) { + $actualTypeData.Members["README"].Value + } + + + $propertyMemberFiles = $memberFiles | Where-Object Name -Match $getSetFile + if ($propertyMemberFiles) { + "### Script Properties" + [Environment]::NewLine + foreach ($memberFile in $propertyMemberFiles | Sort-Object { $_.Name -replace $getSetFile}) { + "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))" + } + } + $methodMemberFiles = $memberFiles | Where-Object Name -NotMatch $getSetFile + if ($methodMemberFiles) { + "### Script Methods" + [Environment]::NewLine + foreach ($memberFile in $methodMemberFiles) { + "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))" + } + } + + ) -join ([Environment]::NewLine) + + $ExtendedTypeDocContent | Set-Content -Path $ExtendedTypeDocFile + if ($?) { + Get-Item -Path $ExtendedTypeDocFile } + + $memberFiles } diff --git a/Formatting/PowerShell.Markdown.Help.format.ps1 b/Formatting/PowerShell.Markdown.Help.format.ps1 index cef29e53..c52843dd 100644 --- a/Formatting/PowerShell.Markdown.Help.format.ps1 +++ b/Formatting/PowerShell.Markdown.Help.format.ps1 @@ -34,7 +34,7 @@ } elseif ($linkedCmd -and ($linkedCmd.Module -like 'microsoft.*' -or $linkedCmd.Source -like 'microsoft.*')) { $linkSrc = if ($linkedCmd.Module) { $linkedCmd.Module} else { $linkedCmd.Source } - "https://docs.microsoft.com/powershell/module/$linkSrc/$linkedCmd" + "https://learn.microsoft.com/powershell/module/$linkSrc/$linkedCmd" } elseif ($helpObject.WikiLink) { $nav.LinkText } elseif ($null -ne $helpObject.DocLink) { @@ -54,17 +54,49 @@ Examples = { if ($helpObject.Examples) { Format-Markdown -Heading "Examples" -headingsize 3 - + + foreach ($example in $helpObject.Examples.Example) { - Format-Markdown -Heading ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') -HeadingSize 4 - - if ($example.Code) { - $example.Code | Format-Markdown -CodeLanguage PowerShell - } - - if ($example.Remarks) { - ($example.Remarks | Out-String -Width 1mb).Trim() - } + + # Combine the code and remarks + $exampleLines = + @( + $example.Code + foreach ($remark in $example.Remarks.text) { + if (-not $remark) { continue } + $remark + } + ) -join ([Environment]::NewLine) -split '(?>\r\n|\n)' # and split into lines + + # Anything until the first non-comment line is a markdown predicate to the example + $nonCommentLine = $false + $markdownLines = @() + + # Go thru each line in the example as part of a loop + $codeBlock = @(foreach ($exampleLine in $exampleLines) { + if ($exampleLine -match '^\#' -and -not $nonCommentLine) { + $markdownLines += $exampleLine -replace '^\#' -replace '^\s+' + } else { + $nonCommentLine = $true + $exampleLine + } + }) -join [Environment]::NewLine + @( + if ($markdownLines) { + $markdownLines -join [Environment]::NewLine + } else { + Format-Markdown -BlockQuote -InputObject ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') + } + + if ($codeBlock) { + $codeBlockAsScriptBlock = try { [ScriptBlock]::Create($codeBlock) } catch { $false } + if ($codeBlockAsScriptBlock) { + $codeBlockAsScriptBlock | Format-Markdown + } else { + $codeBlock + } + } + ) -join [Environment]::NewLine * 2 } } } diff --git a/GitHub/Jobs/BuildHelpOut.psd1 b/GitHub/Jobs/BuildHelpOut.psd1 index 3958580f..1e210162 100644 --- a/GitHub/Jobs/BuildHelpOut.psd1 +++ b/GitHub/Jobs/BuildHelpOut.psd1 @@ -24,7 +24,11 @@ if = '${{github.ref_name != ''master''}}' uses = './' id = 'HelpOutBranch' - } - + }, + @{ + name = 'PSA' + uses = 'StartAutomating/PSA@main' + id = 'PSA' + } ) } \ No newline at end of file diff --git a/HelpOut-Help.xml b/HelpOut-Help.xml index 718cbf0c..ea2a80e1 100644 --- a/HelpOut-Help.xml +++ b/HelpOut-Help.xml @@ -8,7 +8,7 @@ Gets MAML help - 0.4.7 + 0.4.8 Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml. @@ -400,7 +400,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Gets Markdown Help - 0.4.7 + 0.4.8 Gets Help for a given command, in Markdown @@ -666,7 +666,7 @@ If not provided, this will be the order they are defined in the formatter. Gets a script's references - 0.4.7 + 0.4.8 Gets the external references of a given PowerShell command. These are the commands the script calls, and the types the script uses. @@ -792,7 +792,7 @@ If not provided, this will be the order they are defined in the formatter. Gets a Script's story - 0.4.7 + 0.4.8 Gets the Script's "Story" @@ -955,7 +955,7 @@ If not provided, this will be the order they are defined in the formatter. Installs MAML into a module - 0.4.7 + 0.4.8 Installs MAML into a module. @@ -1309,7 +1309,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Determines the percentage of documentation - 0.4.7 + 0.4.8 Determines the percentage of documentation in a given script @@ -1452,7 +1452,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Saves a Module's MAML - 0.4.7 + 0.4.8 Generates a Module's MAML file, and then saves it to the appropriate location. @@ -1713,7 +1713,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Saves a Module's Markdown Help - 0.4.7 + 0.4.8 Get markdown help for each command in a module and saves it to the appropriate location. diff --git a/HelpOut.GitHubWorkflow.PSDevOps.ps1 b/HelpOut.GitHubWorkflow.PSDevOps.ps1 index d322cb7d..387821a2 100644 --- a/HelpOut.GitHubWorkflow.PSDevOps.ps1 +++ b/HelpOut.GitHubWorkflow.PSDevOps.ps1 @@ -10,7 +10,10 @@ Import-BuildStep -Module HelpOut New-GitHubWorkflow -Name "Test, Tag, Release, and Publish" -On Demand, Push -Job PowerShellStaticAnalysis, TestPowerShellOnLinux, TagReleaseAndPublish, - BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml + BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml -Env @{ + "AT_PROTOCOL_HANDLE" = "mrpowershell.bsky.social" + "AT_PROTOCOL_APP_PASSWORD" = '${{ secrets.AT_PROTOCOL_APP_PASSWORD }}' + } New-GitHubWorkflow -On Demand, Released -Job RunGitPub -Name OnIssueOrRelease -OutputPath .\.github\workflows\GitPub.yml diff --git a/HelpOut.PSA.ps1 b/HelpOut.PSA.ps1 new file mode 100644 index 00000000..195643b1 --- /dev/null +++ b/HelpOut.PSA.ps1 @@ -0,0 +1,47 @@ +# Any *.PSA.ps1 file will be run when PSA runs. + +# A good thing to do at the start of this file is to connect. + +Connect-BlueSky + +# If $env:AT_PROTOCOL_HANDLE or $env:AT_PROTOCOL_EMAIL is set, it will be treated as the username +# If $env:AT_PROTOCOL_APP_PASSWORD is set, it will be treated as the App Password. +# _Never_ use your actual BlueSky password + +# Once we're connected, we can do anything our app password allows. + +# However, you _might_ want to output some information first, so that you can see you're connected. + +Get-BskyActorProfile -Actor $env:AT_PROTOCOL_HANDLE -Cache | Out-Host + +# To ensure you're not going to send a skeet on every checkin, it's a good idea to ask what GitHub is up to + +# There will be a variable, $GitHubEvent, that contains information about the event. + +# A fairly common scenario is to perform an annoucement whenever a PR is merged. + +$isMergeToMain = + ($gitHubEvent.head_commit.message -match "Merge Pull Request #(?\d+)") -and + $gitHubEvent.ref -eq 'refs/heads/main' + +if ($isMergeToMain) { + Import-Module .\HelpOut.psd1 -Global -PassThru | Out-Host + $helpOutModule = Get-Module HelpOut + $moduleAndVersion = "$($helpOutModule.Name) $($helpOutModule.Version)" + $fullMessage = @( + "#PowerShell just got a little more helpful: ", + "Auto-generating #PowerShell docs gets easier every release: ", + "#PowerShell people, help yourself to new bits: " | + Get-Random + + "$moduleAndVersion is out!" + ) + + Send-AtProto -Text $fullMessage -WebCard @{ + Url = "https://github.com/StartAutomating/HelpOut" + } -LinkPattern @{ + "HelpOut" = "https://github.com/StartAutomating/HelpOut" + } + + return +} \ No newline at end of file diff --git a/HelpOut.format.ps1xml b/HelpOut.format.ps1xml index 2b3d747f..85fc3cc4 100644 --- a/HelpOut.format.ps1xml +++ b/HelpOut.format.ps1xml @@ -1,9 +1,9 @@ - + - File.Documentation.PercentageDocumentation.Percentage + File.Documentation.Percentage File.Documentation.Percentage Documentation.Percentage @@ -54,20 +54,20 @@ } while ($false) - - $__ = $_ - $ci = . { + + $CellColorValue = $($Script:_LastCellStyle = $($__ = $_;. { & ${HelpOut_Format-Heatmap} -HeatMapMax 20 -InputObject $_.CommentPercent -HeatMapHot "#11ff11" -HeatMapCool "#ff1111" - } - $_ = $__ - if ($ci -is [string]) { - $ci = & ${HelpOut_Format-RichText} -NoClear -ForegroundColor $ci - } else { - $ci = & ${HelpOut_Format-RichText} -NoClear @ci - } - $output = . { '' + ([Math]::Round($_.CommentPercent,2)) + '%' } - @($ci; $output; & ${HelpOut_Format-RichText}) -join "" - + };$_ = $__);$Script:_LastCellStyle) + + if ($CellColorValue -and $CellColorValue -is [string]) { + $CellColorValue = & ${HelpOut_Format-RichText} -NoClear -ForegroundColor $CellColorValue + } elseif (`$CellColorValue -is [Collections.IDictionary]) { + $CellColorValue = & ${HelpOut_Format-RichText} -NoClear @CellColorValue + } + + $output = . { '' + ([Math]::Round($_.CommentPercent,2)) + '%' } + @($CellColorValue; $output; & ${HelpOut_Format-RichText}) -join '' + @@ -147,7 +147,7 @@ } elseif ($linkedCmd -and ($linkedCmd.Module -like 'microsoft.*' -or $linkedCmd.Source -like 'microsoft.*')) { $linkSrc = if ($linkedCmd.Module) { $linkedCmd.Module} else { $linkedCmd.Source } - "https://docs.microsoft.com/powershell/module/$linkSrc/$linkedCmd" + "https://learn.microsoft.com/powershell/module/$linkSrc/$linkedCmd" } elseif ($helpObject.WikiLink) { $nav.LinkText } elseif ($null -ne $helpObject.DocLink) { @@ -167,17 +167,49 @@ Examples = { if ($helpObject.Examples) { & ${HelpOut_Format-Markdown} -Heading "Examples" -headingsize 3 - + + foreach ($example in $helpObject.Examples.Example) { - & ${HelpOut_Format-Markdown} -Heading ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') -HeadingSize 4 - - if ($example.Code) { - $example.Code | & ${HelpOut_Format-Markdown} -CodeLanguage PowerShell - } - - if ($example.Remarks) { - ($example.Remarks | Out-String -Width 1mb).Trim() - } + + # Combine the code and remarks + $exampleLines = + @( + $example.Code + foreach ($remark in $example.Remarks.text) { + if (-not $remark) { continue } + $remark + } + ) -join ([Environment]::NewLine) -split '(?>\r\n|\n)' # and split into lines + + # Anything until the first non-comment line is a markdown predicate to the example + $nonCommentLine = $false + $markdownLines = @() + + # Go thru each line in the example as part of a loop + $codeBlock = @(foreach ($exampleLine in $exampleLines) { + if ($exampleLine -match '^\#' -and -not $nonCommentLine) { + $markdownLines += $exampleLine -replace '^\#' -replace '^\s+' + } else { + $nonCommentLine = $true + $exampleLine + } + }) -join [Environment]::NewLine + @( + if ($markdownLines) { + $markdownLines -join [Environment]::NewLine + } else { + & ${HelpOut_Format-Markdown} -BlockQuote -InputObject ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') + } + + if ($codeBlock) { + $codeBlockAsScriptBlock = try { [ScriptBlock]::Create($codeBlock) } catch { $false } + if ($codeBlockAsScriptBlock) { + $codeBlockAsScriptBlock | & ${HelpOut_Format-Markdown} + } else { + $codeBlock + } + } + ) -join [Environment]::NewLine * 2 } } } @@ -853,7 +885,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co } elseif ($canUseANSI) { # For ANSI, - '' + $esc + ']8m;;' + $Link + $esc + '\' + '' + $esc + ']8;;' + $Link + $esc + '\' } } @@ -1439,6 +1471,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co ) begin { + if (-not $Depth) { $depth = $FormatEnumerationLimit } $toYaml = { param( [Parameter(ValueFromPipeline,Position=0)]$Object, diff --git a/HelpOut.psd1 b/HelpOut.psd1 index 9e2cfbf3..d8747a56 100644 --- a/HelpOut.psd1 +++ b/HelpOut.psd1 @@ -7,7 +7,7 @@ ModuleToProcess='HelpOut.psm1' FormatsToProcess='HelpOut.format.ps1xml' TypesToProcess='HelpOut.types.ps1xml' - ModuleVersion='0.4.7' + ModuleVersion='0.4.8' PrivateData = @{ PSData = @{ ProjectURI = 'https://github.com/StartAutomating/HelpOut' @@ -15,10 +15,20 @@ Tags = 'Markdown', 'Help','PowerShell' ReleaseNotes = @' -### HelpOut 0.4.7: +### HelpOut 0.4.8: -* Get-MarkdownHelp: Automatically renaming help about aliases (Fixes #130) -* Save-MarkdownHelp: Improving resiliency (avoiding null burps) (Fixes #128) +* Markdown Help Improvements: + * Fixing Long Examples (Fixes #141) + * Allowing first comment lines in an example to be markdown (#143) + * Also, switching numbered example headings to blockquotes +* Save-MarkdownHelp updates: + * Fixing Piping Behavior (#140) + * Not Saving to illegal windows paths (#132) +* Improving Extended Types Doc Generation + * Now puts extended type documentation into subfolders (#135) + * Also, generates a summary file for each type (#133) +* Updating links to Microsoft modules (#142) +* Integrating PSA into HelpOut (#144) --- diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 08be6955..3e2f63e6 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -1,5 +1,5 @@ - + PowerShell.Markdown.Help @@ -42,6 +42,8 @@ $this | Saves a Markdown Help Topic .DESCRIPTION Saves a Markdown Help Topic to a file. +.NOTES + This will not save to files that have illegal names on Windows. .EXAMPLE (Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") .LINK @@ -59,6 +61,11 @@ $FilePath, $View = 'PowerShell.Markdown.Help' ) +if ($filePath -match '[\<\>\|\?\*]') { + Write-Warning "Will not .Save to $filePath, because that path will not be readable on all operating systems." + return +} + if (-not (Test-Path $FilePath)) { $createdFile = New-Item -ItemType File -Path $FilePath -Force if (-not $createdFile) { return } diff --git a/Save-MarkdownHelp.ps1 b/Save-MarkdownHelp.ps1 index e6dd6a16..24bb68ad 100644 --- a/Save-MarkdownHelp.ps1 +++ b/Save-MarkdownHelp.ps1 @@ -14,7 +14,8 @@ #> param( # The name of one or more modules. - [Parameter(ParameterSetName='ByModule',ValueFromPipelineByPropertyName=$true)] + [Parameter(ParameterSetName='ByModule',ValueFromPipelineByPropertyName)] + [Alias('Name')] [string[]] $Module, @@ -172,15 +173,18 @@ } } + $c = 0 + $t = $Module.Count #region Save the Markdowns foreach ($m in $Module) { # Walk thru the list of module names. if ($t -gt 1) { $c++ + $p = $c * 100 / $t Write-Progress 'Saving Markdown' $m -PercentComplete $p -Id $id } - $theModule = Get-Module $m # Find the module + $theModule = Get-Module $module # Find the module if (-not $theModule) { continue } # (continue if we couldn't). $theModuleRoot = $theModule | Split-Path # Find the module's root. if (-not $psBoundParameters.OutputPath) { # If no -OutputPath was provided @@ -522,8 +526,15 @@ } } #endregion Run Extensions to this Command + } + + if ($t -gt 1) { + Write-Progress 'Saving Markdown' 'Complete' -Completed -Id $id } + #endregion Save the Markdowns + } + end { if ($PassThru -and $ReplaceLink) { $linkFinder = [Regex]::new(" (?\!)? # If there is an exclamation point, then it is an image link @@ -571,10 +582,5 @@ } } } - - if ($t -gt 1) { - Write-Progress 'Saving Markdown' 'Complete' -Completed -Id $id - } - #endregion Save the Markdowns } } diff --git a/Types/PowerShell.Markdown.Help/Save.ps1 b/Types/PowerShell.Markdown.Help/Save.ps1 index 426e10b4..78d14af3 100644 --- a/Types/PowerShell.Markdown.Help/Save.ps1 +++ b/Types/PowerShell.Markdown.Help/Save.ps1 @@ -3,6 +3,8 @@ Saves a Markdown Help Topic .DESCRIPTION Saves a Markdown Help Topic to a file. +.NOTES + This will not save to files that have illegal names on Windows. .EXAMPLE (Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") .LINK @@ -20,6 +22,11 @@ $FilePath, $View = 'PowerShell.Markdown.Help' ) +if ($filePath -match '[\<\>\|\?\*]') { + Write-Warning "Will not .Save to $filePath, because that path will not be readable on all operating systems." + return +} + if (-not (Test-Path $FilePath)) { $createdFile = New-Item -ItemType File -Path $FilePath -Force if (-not $createdFile) { return } diff --git a/allcommands.ps1 b/allcommands.ps1 index 6e1d5f38..e8de9ad0 100644 --- a/allcommands.ps1 +++ b/allcommands.ps1 @@ -1433,7 +1433,8 @@ function Save-MarkdownHelp #> param( # The name of one or more modules. - [Parameter(ParameterSetName='ByModule',ValueFromPipelineByPropertyName=$true)] + [Parameter(ParameterSetName='ByModule',ValueFromPipelineByPropertyName)] + [Alias('Name')] [string[]] $Module, @@ -1591,15 +1592,18 @@ function Save-MarkdownHelp } } + $c = 0 + $t = $Module.Count #region Save the Markdowns foreach ($m in $Module) { # Walk thru the list of module names. if ($t -gt 1) { $c++ + $p = $c * 100 / $t Write-Progress 'Saving Markdown' $m -PercentComplete $p -Id $id } - $theModule = Get-Module $m # Find the module + $theModule = Get-Module $module # Find the module if (-not $theModule) { continue } # (continue if we couldn't). $theModuleRoot = $theModule | Split-Path # Find the module's root. if (-not $psBoundParameters.OutputPath) { # If no -OutputPath was provided @@ -1941,8 +1945,15 @@ function Save-MarkdownHelp } } #endregion Run Extensions to this Command + } + + if ($t -gt 1) { + Write-Progress 'Saving Markdown' 'Complete' -Completed -Id $id } + #endregion Save the Markdowns + } + end { if ($PassThru -and $ReplaceLink) { $linkFinder = [Regex]::new(" (?\!)? # If there is an exclamation point, then it is an image link @@ -1990,10 +2001,5 @@ function Save-MarkdownHelp } } } - - if ($t -gt 1) { - Write-Progress 'Saving Markdown' 'Complete' -Completed -Id $id - } - #endregion Save the Markdowns } } diff --git a/docs/Assets/HelpOut.svg b/docs/Assets/HelpOut.svg index 2cdd4813..737be7de 100644 --- a/docs/Assets/HelpOut.svg +++ b/docs/Assets/HelpOut.svg @@ -1,4 +1,5 @@ + diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 7af12ff2..a729075f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,3 +1,20 @@ +### HelpOut 0.4.8: + +* Markdown Help Improvements: + * Fixing Long Examples (Fixes #141) + * Allowing first comment lines in an example to be markdown (#143) + * Also, switching numbered example headings to blockquotes +* Save-MarkdownHelp updates: + * Fixing Piping Behavior (#140) + * Not Saving to illegal windows paths (#132) +* Improving Extended Types Doc Generation + * Now puts extended type documentation into subfolders (#135) + * Also, generates a summary file for each type (#133) +* Updating links to Microsoft modules (#142) +* Integrating PSA into HelpOut (#144) + +--- + ### HelpOut 0.4.7: * Get-MarkdownHelp: Automatically renaming help about aliases (Fixes #130) diff --git a/docs/ConvertTo-MAML.md b/docs/ConvertTo-MAML.md index 9107c78e..c43a837c 100644 --- a/docs/ConvertTo-MAML.md +++ b/docs/ConvertTo-MAML.md @@ -56,7 +56,7 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ### Related Links -* [Get-Help](https://docs.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) +* [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) @@ -70,28 +70,28 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-MAML -Name Get-MAML ``` +> EXAMPLE 2 -#### EXAMPLE 2 ```PowerShell Get-Command Get-MAML | Get-MAML ``` +> EXAMPLE 3 -#### EXAMPLE 3 ```PowerShell Get-MAML -Name Get-MAML -Compact ``` +> EXAMPLE 4 -#### EXAMPLE 4 ```PowerShell Get-MAML -Name Get-MAML -XML ``` - --- diff --git a/docs/Get-MAML.md b/docs/Get-MAML.md index 9107c78e..c43a837c 100644 --- a/docs/Get-MAML.md +++ b/docs/Get-MAML.md @@ -56,7 +56,7 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ### Related Links -* [Get-Help](https://docs.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) +* [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) @@ -70,28 +70,28 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-MAML -Name Get-MAML ``` +> EXAMPLE 2 -#### EXAMPLE 2 ```PowerShell Get-Command Get-MAML | Get-MAML ``` +> EXAMPLE 3 -#### EXAMPLE 3 ```PowerShell Get-MAML -Name Get-MAML -Compact ``` +> EXAMPLE 4 -#### EXAMPLE 4 ```PowerShell Get-MAML -Name Get-MAML -XML ``` - --- diff --git a/docs/Get-MarkdownHelp.md b/docs/Get-MarkdownHelp.md index 342f0c60..09bed0c5 100644 --- a/docs/Get-MarkdownHelp.md +++ b/docs/Get-MarkdownHelp.md @@ -75,7 +75,7 @@ Gets Help for a given command, in Markdown -* [Get-Help](https://docs.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) +* [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) @@ -85,13 +85,13 @@ Gets Help for a given command, in Markdown ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-MarkdownHelp Get-Help ``` - --- diff --git a/docs/Get-ScriptReference.md b/docs/Get-ScriptReference.md index 4f69d713..4a406be1 100644 --- a/docs/Get-ScriptReference.md +++ b/docs/Get-ScriptReference.md @@ -44,13 +44,13 @@ Gets the external references of a given PowerShell command. These are the comma ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-Command Get-ScriptReference | Get-ScriptReference ``` - --- diff --git a/docs/Get-ScriptStory.md b/docs/Get-ScriptStory.md index cb213474..368b5332 100644 --- a/docs/Get-ScriptStory.md +++ b/docs/Get-ScriptStory.md @@ -53,13 +53,13 @@ Script Stories are a simple markdown summary of all single-line comments within ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-Command Get-ScriptStory | Get-ScriptStory ``` - --- diff --git a/docs/Install-MAML.md b/docs/Install-MAML.md index ec52fcf3..948a1153 100644 --- a/docs/Install-MAML.md +++ b/docs/Install-MAML.md @@ -108,13 +108,13 @@ Ideally, you should use the allcommands script ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Install-MAML -Module HelpOut ``` - --- diff --git a/docs/Measure-Help.md b/docs/Measure-Help.md index b9e513d2..c890b10a 100644 --- a/docs/Measure-Help.md +++ b/docs/Measure-Help.md @@ -44,7 +44,7 @@ Determines the percentage of documentation in a given script ### Related Links -* [Get-Help](https://docs.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) +* [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) @@ -54,17 +54,18 @@ Determines the percentage of documentation in a given script ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell dir -Filter *.ps1 | Measure-Help ``` +> EXAMPLE 2 -#### EXAMPLE 2 ```PowerShell Get-Command -Module HelpOut | Measure-Help ``` +> EXAMPLE 3 -#### EXAMPLE 3 ```PowerShell Measure-Help { # This script has some documentation, and then a bunch of code that literally does nothing @@ -75,7 +76,6 @@ Measure-Help { ``` - --- diff --git a/docs/PowerShell.Markdown.Help.HideSection.md b/docs/PowerShell/Markdown/Help/HideSection.md similarity index 100% rename from docs/PowerShell.Markdown.Help.HideSection.md rename to docs/PowerShell/Markdown/Help/HideSection.md diff --git a/docs/PowerShell/Markdown/Help/README.md b/docs/PowerShell/Markdown/Help/README.md new file mode 100644 index 00000000..12d67e2c --- /dev/null +++ b/docs/PowerShell/Markdown/Help/README.md @@ -0,0 +1,10 @@ +## PowerShell.Markdown.Help + + +### Script Methods + + +* [HideSection](HideSection.md) +* [Save](Save.md) +* [ShowSection](ShowSection.md) +* [ToMarkdown](ToMarkdown.md) diff --git a/docs/PowerShell.Markdown.Help.Save.md b/docs/PowerShell/Markdown/Help/Save.md similarity index 92% rename from docs/PowerShell.Markdown.Help.Save.md rename to docs/PowerShell/Markdown/Help/Save.md index 6505aced..0028014a 100644 --- a/docs/PowerShell.Markdown.Help.Save.md +++ b/docs/PowerShell/Markdown/Help/Save.md @@ -50,13 +50,13 @@ Saves a Markdown Help Topic to a file. ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell (Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") ``` - --- @@ -95,4 +95,12 @@ This would need to be declared in a .format.ps1xml file by another loaded module +--- + + +### Notes +This will not save to files that have illegal names on Windows. + + + --- diff --git a/docs/PowerShell.Markdown.Help.ShowSection.md b/docs/PowerShell/Markdown/Help/ShowSection.md similarity index 100% rename from docs/PowerShell.Markdown.Help.ShowSection.md rename to docs/PowerShell/Markdown/Help/ShowSection.md diff --git a/docs/PowerShell.Markdown.Help.ToMarkdown.md b/docs/PowerShell/Markdown/Help/ToMarkdown.md similarity index 98% rename from docs/PowerShell.Markdown.Help.ToMarkdown.md rename to docs/PowerShell/Markdown/Help/ToMarkdown.md index 0983938d..b6f51133 100644 --- a/docs/PowerShell.Markdown.Help.ToMarkdown.md +++ b/docs/PowerShell/Markdown/Help/ToMarkdown.md @@ -36,13 +36,13 @@ Returns the content of this help topic as a markdown string. ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell (Get-MarkDownHelp Get-MarkDownHelp).ToMarkdown() ``` - --- diff --git a/docs/Save-MAML.md b/docs/Save-MAML.md index f451cc55..d24c374c 100644 --- a/docs/Save-MAML.md +++ b/docs/Save-MAML.md @@ -62,23 +62,23 @@ Generates a Module's MAML file, and then saves it to the appropriate location. ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Save-Maml -Module HelpOut ``` +> EXAMPLE 2 -#### EXAMPLE 2 ```PowerShell Save-Maml -Module HelpOut -WhatIf ``` +> EXAMPLE 3 -#### EXAMPLE 3 ```PowerShell Save-Maml -Module HelpOut -PassThru ``` - --- diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index e3856bde..574fd927 100644 --- a/docs/Save-MarkdownHelp.md +++ b/docs/Save-MarkdownHelp.md @@ -29,7 +29,7 @@ Parameters: - Name: Module Type: System.String[] Aliases: - + - Name - Name: NoValidValueEnumeration Type: System.Management.Automation.SwitchParameter Aliases: @@ -130,18 +130,18 @@ Get markdown help for each command in a module and saves it to the appropriate l ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Save-MarkdownHelp -Module HelpOut # Save Markdown to HelpOut/docs ``` +> EXAMPLE 2 -#### EXAMPLE 2 ```PowerShell Save-MarkdownHelp -Module HelpOut -Wiki # Save Markdown to ../HelpOut.wiki ``` - --- @@ -155,9 +155,9 @@ The name of one or more modules. -|Type |Required|Position|PipelineInput | -|------------|--------|--------|---------------------| -|`[String[]]`|false |named |true (ByPropertyName)| +|Type |Required|Position|PipelineInput |Aliases| +|------------|--------|--------|---------------------|-------| +|`[String[]]`|false |named |true (ByPropertyName)|Name |