From 2b31137a3aba3598050906b353d7435d6388aa3b Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Sat, 1 Jul 2023 15:35:34 -0700 Subject: [PATCH 01/53] Not Saving to illegal windows paths (Fixes #132) --- Types/PowerShell.Markdown.Help/Save.ps1 | 7 +++++++ 1 file changed, 7 insertions(+) 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 } From 9fb8e6c72e82b0dbcaab2d7a904679242ab7c319 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sat, 1 Jul 2023 22:36:54 +0000 Subject: [PATCH 02/53] Not Saving to illegal windows paths (Fixes #132) --- HelpOut.types.ps1xml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 08be6955..daab0bcd 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -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 } From c33eb1747bc9cf187f934c58700e238537aa24b4 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sat, 1 Jul 2023 22:37:04 +0000 Subject: [PATCH 03/53] Not Saving to illegal windows paths (Fixes #132) --- docs/PowerShell.Markdown.Help.Save.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/PowerShell.Markdown.Help.Save.md b/docs/PowerShell.Markdown.Help.Save.md index 6505aced..a8a95418 100644 --- a/docs/PowerShell.Markdown.Help.Save.md +++ b/docs/PowerShell.Markdown.Help.Save.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. + + + --- From 606a03889f946a31631a640e6037ad3e34bc49e0 Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 19:04:24 -0700 Subject: [PATCH 04/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- Formatting/PowerShell.Markdown.Help.format.ps1 | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/Formatting/PowerShell.Markdown.Help.format.ps1 b/Formatting/PowerShell.Markdown.Help.format.ps1 index cef29e53..6d726e95 100644 --- a/Formatting/PowerShell.Markdown.Help.format.ps1 +++ b/Formatting/PowerShell.Markdown.Help.format.ps1 @@ -58,13 +58,14 @@ 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() - } + @( + $example.Code + foreach ($remark in $example.Remarks.text) { + if (-not $remark) { continue } + $remark + } + ) -join ([Environment]::NewLine) | + Format-Markdown -CodeLanguage PowerShell } } } From 8851566a3037dfafc8b80d937b657e8c13777791 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:04 +0000 Subject: [PATCH 05/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- Assets/HelpOut.svg | 1 + 1 file changed, 1 insertion(+) 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 @@ + From 367a7573ebc2e357f748b7295fb5c7304972e972 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:20 +0000 Subject: [PATCH 06/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- HelpOut.format.ps1xml | 48 ++++++++++++++++++++++--------------------- 1 file changed, 25 insertions(+), 23 deletions(-) diff --git a/HelpOut.format.ps1xml b/HelpOut.format.ps1xml index 2b3d747f..b94f751c 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 '' + @@ -171,13 +171,14 @@ 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() - } + @( + $example.Code + foreach ($remark in $example.Remarks.text) { + if (-not $remark) { continue } + $remark + } + ) -join ([Environment]::NewLine) | + & ${HelpOut_Format-Markdown} -CodeLanguage PowerShell } } } @@ -853,7 +854,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 +1440,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, From baaa765a1a660f197f0be38ce05ea63d1b25cbb9 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:21 +0000 Subject: [PATCH 07/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- HelpOut.types.ps1xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index daab0bcd..3e2f63e6 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -1,5 +1,5 @@ - + PowerShell.Markdown.Help From 0f1f6d6cceafbb5eed8eb413e52f5b7ba61b9a84 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:31 +0000 Subject: [PATCH 08/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Get-MAML.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/Get-MAML.md b/docs/Get-MAML.md index 9107c78e..f6875ebd 100644 --- a/docs/Get-MAML.md +++ b/docs/Get-MAML.md @@ -74,24 +74,20 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ```PowerShell Get-MAML -Name Get-MAML ``` - #### EXAMPLE 2 ```PowerShell Get-Command Get-MAML | Get-MAML ``` - #### EXAMPLE 3 ```PowerShell Get-MAML -Name Get-MAML -Compact ``` - #### EXAMPLE 4 ```PowerShell Get-MAML -Name Get-MAML -XML ``` - --- From e15cf43e0d1af60351cb2ea6282b46e01d78c792 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:31 +0000 Subject: [PATCH 09/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Get-MarkdownHelp.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Get-MarkdownHelp.md b/docs/Get-MarkdownHelp.md index 342f0c60..73ef0b13 100644 --- a/docs/Get-MarkdownHelp.md +++ b/docs/Get-MarkdownHelp.md @@ -91,7 +91,6 @@ Get-MarkdownHelp Get-Help ``` - --- From 0a60decc36dd5ab7b26f44a77c7a6cd2b050003c Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:32 +0000 Subject: [PATCH 10/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Get-ScriptReference.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Get-ScriptReference.md b/docs/Get-ScriptReference.md index 4f69d713..27000562 100644 --- a/docs/Get-ScriptReference.md +++ b/docs/Get-ScriptReference.md @@ -50,7 +50,6 @@ Get-Command Get-ScriptReference | Get-ScriptReference ``` - --- From 15cb768bd1bc1927e2204e4492de7de5c256fd40 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:32 +0000 Subject: [PATCH 11/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Get-ScriptStory.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Get-ScriptStory.md b/docs/Get-ScriptStory.md index cb213474..b7d3769a 100644 --- a/docs/Get-ScriptStory.md +++ b/docs/Get-ScriptStory.md @@ -59,7 +59,6 @@ Get-Command Get-ScriptStory | Get-ScriptStory ``` - --- From bc4c929a89353c9c61c28894fb2f56b37784f3fa Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:32 +0000 Subject: [PATCH 12/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Install-MAML.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/Install-MAML.md b/docs/Install-MAML.md index ec52fcf3..20d26bed 100644 --- a/docs/Install-MAML.md +++ b/docs/Install-MAML.md @@ -114,7 +114,6 @@ Install-MAML -Module HelpOut ``` - --- From 201cdc68538d01ad5b52bef4fe69ec9b640382ce Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:32 +0000 Subject: [PATCH 13/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Measure-Help.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/Measure-Help.md b/docs/Measure-Help.md index b9e513d2..417e8fdd 100644 --- a/docs/Measure-Help.md +++ b/docs/Measure-Help.md @@ -58,12 +58,10 @@ Determines the percentage of documentation in a given script ```PowerShell dir -Filter *.ps1 | Measure-Help ``` - #### EXAMPLE 2 ```PowerShell Get-Command -Module HelpOut | Measure-Help ``` - #### EXAMPLE 3 ```PowerShell Measure-Help { @@ -75,7 +73,6 @@ Measure-Help { ``` - --- From 586465fb95d3153451fe273c7e089632f58b619c Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:33 +0000 Subject: [PATCH 14/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Save-MAML.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/Save-MAML.md b/docs/Save-MAML.md index f451cc55..69f53d55 100644 --- a/docs/Save-MAML.md +++ b/docs/Save-MAML.md @@ -66,19 +66,16 @@ Generates a Module's MAML file, and then saves it to the appropriate location. ```PowerShell Save-Maml -Module HelpOut ``` - #### EXAMPLE 2 ```PowerShell Save-Maml -Module HelpOut -WhatIf ``` - #### EXAMPLE 3 ```PowerShell Save-Maml -Module HelpOut -PassThru ``` - --- From 1883b62e6a7b0ed121b1af099b43da5a73e1d5d0 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:33 +0000 Subject: [PATCH 15/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Save-MarkdownHelp.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index e3856bde..d173c04f 100644 --- a/docs/Save-MarkdownHelp.md +++ b/docs/Save-MarkdownHelp.md @@ -134,14 +134,12 @@ Get markdown help for each command in a module and saves it to the appropriate l ```PowerShell Save-MarkdownHelp -Module HelpOut # Save Markdown to HelpOut/docs ``` - #### EXAMPLE 2 ```PowerShell Save-MarkdownHelp -Module HelpOut -Wiki # Save Markdown to ../HelpOut.wiki ``` - --- From 18d16ed50504669ad414cfdd87caed961ac7b610 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:33 +0000 Subject: [PATCH 16/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/ConvertTo-MAML.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/ConvertTo-MAML.md b/docs/ConvertTo-MAML.md index 9107c78e..f6875ebd 100644 --- a/docs/ConvertTo-MAML.md +++ b/docs/ConvertTo-MAML.md @@ -74,24 +74,20 @@ Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xm ```PowerShell Get-MAML -Name Get-MAML ``` - #### EXAMPLE 2 ```PowerShell Get-Command Get-MAML | Get-MAML ``` - #### EXAMPLE 3 ```PowerShell Get-MAML -Name Get-MAML -Compact ``` - #### EXAMPLE 4 ```PowerShell Get-MAML -Name Get-MAML -XML ``` - --- From fc6cd3211f34c6284f6b301e91f6bf785a226a48 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:34 +0000 Subject: [PATCH 17/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/Assets/HelpOut.svg | 1 + 1 file changed, 1 insertion(+) 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 @@ + From d0f089786386289d3302d8442d132492dbb325be Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:35 +0000 Subject: [PATCH 18/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/PowerShell.Markdown.Help.Save.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/PowerShell.Markdown.Help.Save.md b/docs/PowerShell.Markdown.Help.Save.md index a8a95418..1b0e2bda 100644 --- a/docs/PowerShell.Markdown.Help.Save.md +++ b/docs/PowerShell.Markdown.Help.Save.md @@ -56,7 +56,6 @@ Saves a Markdown Help Topic to a file. ``` - --- From cfb69414bcfdd8d71b049570f5fa87877f640654 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:05:35 +0000 Subject: [PATCH 19/53] Markdown Help Formatter - Fixing Long Examples (Fixes #141) --- docs/PowerShell.Markdown.Help.ToMarkdown.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/PowerShell.Markdown.Help.ToMarkdown.md b/docs/PowerShell.Markdown.Help.ToMarkdown.md index 0983938d..b44f9f15 100644 --- a/docs/PowerShell.Markdown.Help.ToMarkdown.md +++ b/docs/PowerShell.Markdown.Help.ToMarkdown.md @@ -42,7 +42,6 @@ Returns the content of this help topic as a markdown string. ``` - --- From c5eda5f744e2cedc89b30b522c532f18d2863dab Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 19:23:40 -0700 Subject: [PATCH 20/53] Save-MarkdownHelp - Fixing Piping Behavior (Fixes #140) --- Save-MarkdownHelp.ps1 | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) 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 } } From 99bbb8d0dae0ebf6194f54551194130f639a80da Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:24:39 +0000 Subject: [PATCH 21/53] Save-MarkdownHelp - Fixing Piping Behavior (Fixes #140) --- docs/Save-MarkdownHelp.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index d173c04f..d49d2d9b 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: @@ -153,9 +153,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 | From e9f5c587e58d7a2b01893a8df4e2d034cd1d2fa1 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 02:24:40 +0000 Subject: [PATCH 22/53] Save-MarkdownHelp - Fixing Piping Behavior (Fixes #140) --- allcommands.ps1 | 20 +++++++++++++------- 1 file changed, 13 insertions(+), 7 deletions(-) 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 } } From 87e944bd212ba47b7c2be0c59a5db1cced0aee5b Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:08:19 -0700 Subject: [PATCH 23/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- .../PowerShell.Markdown.Help.format.ps1 | 49 +++++++++++++++---- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/Formatting/PowerShell.Markdown.Help.format.ps1 b/Formatting/PowerShell.Markdown.Help.format.ps1 index 6d726e95..6db0a8fb 100644 --- a/Formatting/PowerShell.Markdown.Help.format.ps1 +++ b/Formatting/PowerShell.Markdown.Help.format.ps1 @@ -54,18 +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 - + + # 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 @( - $example.Code - foreach ($remark in $example.Remarks.text) { - if (-not $remark) { continue } - $remark + 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) | - Format-Markdown -CodeLanguage PowerShell + ) -join [Environment]::NewLine * 2 } } } From 5ed6dddbdb4e007dbcde3b689966a97de1d9f22e Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:14 +0000 Subject: [PATCH 24/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- HelpOut.format.ps1xml | 49 +++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 9 deletions(-) diff --git a/HelpOut.format.ps1xml b/HelpOut.format.ps1xml index b94f751c..9106ee35 100644 --- a/HelpOut.format.ps1xml +++ b/HelpOut.format.ps1xml @@ -167,18 +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 - + + # 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 @( - $example.Code - foreach ($remark in $example.Remarks.text) { - if (-not $remark) { continue } - $remark + 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) | - & ${HelpOut_Format-Markdown} -CodeLanguage PowerShell + ) -join [Environment]::NewLine * 2 } } } From b356101c981c4d06a05f42deb76a8e2cbd22cb68 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:22 +0000 Subject: [PATCH 25/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Get-MAML.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/Get-MAML.md b/docs/Get-MAML.md index f6875ebd..1c535c48 100644 --- a/docs/Get-MAML.md +++ b/docs/Get-MAML.md @@ -70,19 +70,23 @@ 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 ``` From 189629c1b35a21583fed40d4c30dc8cd4f7b4cab Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:23 +0000 Subject: [PATCH 26/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Get-MarkdownHelp.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Get-MarkdownHelp.md b/docs/Get-MarkdownHelp.md index 73ef0b13..2ff4d9a5 100644 --- a/docs/Get-MarkdownHelp.md +++ b/docs/Get-MarkdownHelp.md @@ -85,7 +85,8 @@ Gets Help for a given command, in Markdown ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Get-MarkdownHelp Get-Help ``` From 9f2c907286c64ec562ccfb362f6a2818172427f7 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:23 +0000 Subject: [PATCH 27/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Get-ScriptReference.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Get-ScriptReference.md b/docs/Get-ScriptReference.md index 27000562..4a406be1 100644 --- a/docs/Get-ScriptReference.md +++ b/docs/Get-ScriptReference.md @@ -44,7 +44,8 @@ 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 ``` From 72f4bc5f342489deae2980ed82e8f5eec0223d11 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:23 +0000 Subject: [PATCH 28/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Get-ScriptStory.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Get-ScriptStory.md b/docs/Get-ScriptStory.md index b7d3769a..368b5332 100644 --- a/docs/Get-ScriptStory.md +++ b/docs/Get-ScriptStory.md @@ -53,7 +53,8 @@ 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 ``` From bc803d7421dd87304616e47b5cd8c2227f4fdfd9 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:23 +0000 Subject: [PATCH 29/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Install-MAML.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/Install-MAML.md b/docs/Install-MAML.md index 20d26bed..948a1153 100644 --- a/docs/Install-MAML.md +++ b/docs/Install-MAML.md @@ -108,7 +108,8 @@ Ideally, you should use the allcommands script ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell Install-MAML -Module HelpOut ``` From d58542becc5376ba2eabc58813f58a5145a0b30d Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:24 +0000 Subject: [PATCH 30/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Measure-Help.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/Measure-Help.md b/docs/Measure-Help.md index 417e8fdd..5921a6de 100644 --- a/docs/Measure-Help.md +++ b/docs/Measure-Help.md @@ -54,15 +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 From 59c2de6b3d339ed20a14c4166b91fb985487c24e Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:24 +0000 Subject: [PATCH 31/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Save-MAML.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/Save-MAML.md b/docs/Save-MAML.md index 69f53d55..d24c374c 100644 --- a/docs/Save-MAML.md +++ b/docs/Save-MAML.md @@ -62,15 +62,18 @@ 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 ``` From f8b4b5c483bc0acd443652d143a19b3c4effcd30 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:24 +0000 Subject: [PATCH 32/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/Save-MarkdownHelp.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index d49d2d9b..574fd927 100644 --- a/docs/Save-MarkdownHelp.md +++ b/docs/Save-MarkdownHelp.md @@ -130,11 +130,13 @@ 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 ``` From 05df694ed627cbcf907525d9d8faf62295c35fea Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:24 +0000 Subject: [PATCH 33/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/ConvertTo-MAML.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/docs/ConvertTo-MAML.md b/docs/ConvertTo-MAML.md index f6875ebd..1c535c48 100644 --- a/docs/ConvertTo-MAML.md +++ b/docs/ConvertTo-MAML.md @@ -70,19 +70,23 @@ 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 ``` From c0ac71688aba0bfddf41290c8d62a286c375a0a6 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:25 +0000 Subject: [PATCH 34/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/PowerShell.Markdown.Help.Save.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/PowerShell.Markdown.Help.Save.md b/docs/PowerShell.Markdown.Help.Save.md index 1b0e2bda..0028014a 100644 --- a/docs/PowerShell.Markdown.Help.Save.md +++ b/docs/PowerShell.Markdown.Help.Save.md @@ -50,7 +50,8 @@ Saves a Markdown Help Topic to a file. ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell (Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") ``` From dd49dee05b87ff5b3600ec6fcbcc28adcb8bd37d Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:09:25 +0000 Subject: [PATCH 35/53] Allowing first comment lines in an example to be markdown (Fixes #143) --- docs/PowerShell.Markdown.Help.ToMarkdown.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/PowerShell.Markdown.Help.ToMarkdown.md b/docs/PowerShell.Markdown.Help.ToMarkdown.md index b44f9f15..b6f51133 100644 --- a/docs/PowerShell.Markdown.Help.ToMarkdown.md +++ b/docs/PowerShell.Markdown.Help.ToMarkdown.md @@ -36,7 +36,8 @@ Returns the content of this help topic as a markdown string. ### Examples -#### EXAMPLE 1 +> EXAMPLE 1 + ```PowerShell (Get-MarkDownHelp Get-MarkDownHelp).ToMarkdown() ``` From 819cc50608da7a39b36e4339222c850ba36ae608 Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:36:15 -0700 Subject: [PATCH 36/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- ...HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 | 57 +++++++++++++++++-- 1 file changed, 52 insertions(+), 5 deletions(-) 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 } From fbfccaea17dea455db6f89236fc4ebfb12f5df6e Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:37:17 +0000 Subject: [PATCH 37/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- docs/PowerShell/Markdown/Help/README.md | 10 ++++++++++ 1 file changed, 10 insertions(+) create mode 100644 docs/PowerShell/Markdown/Help/README.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) From c961bc7262ef544232339d4c7c0c2f96ca9d263c Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:37:17 +0000 Subject: [PATCH 38/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- docs/PowerShell/Markdown/Help/HideSection.md | 73 ++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/PowerShell/Markdown/Help/HideSection.md diff --git a/docs/PowerShell/Markdown/Help/HideSection.md b/docs/PowerShell/Markdown/Help/HideSection.md new file mode 100644 index 00000000..d7d845c6 --- /dev/null +++ b/docs/PowerShell/Markdown/Help/HideSection.md @@ -0,0 +1,73 @@ +--- +CommandName: PowerShell.Markdown.Help.HideSection +Parameters: + - Name: SectionNames + Type: System.String[] + Aliases: + - SectionName + +Synopsis: Hides sections of markdown help +Description: | + + Hides sections of a command's markdown help. +--- + + +PowerShell.Markdown.Help.HideSection() +-------------------------------------- + + + + +### Synopsis +Hides sections of markdown help + + + +--- + + +### Description + +Hides sections of a command's markdown help. + + + +--- + + +### Parameters +#### **SectionNames** + +One or more section names. + + + +Valid Values: + +* Name +* Synopsis +* Description +* RelatedLinks +* Examples +* Parameters +* Inputs +* Outputs +* Notes +* Story +* Syntax + + + + + + +|Type |Required|Position|PipelineInput|Aliases | +|------------|--------|--------|-------------|-----------| +|`[String[]]`|false |1 |false |SectionName| + + + + + +--- From 850df167a5ef028d3ff7ff555eb07edd9c43fddd Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:37:17 +0000 Subject: [PATCH 39/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- docs/PowerShell/Markdown/Help/Save.md | 106 ++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 docs/PowerShell/Markdown/Help/Save.md diff --git a/docs/PowerShell/Markdown/Help/Save.md b/docs/PowerShell/Markdown/Help/Save.md new file mode 100644 index 00000000..0028014a --- /dev/null +++ b/docs/PowerShell/Markdown/Help/Save.md @@ -0,0 +1,106 @@ +--- +CommandName: PowerShell.Markdown.Help.Save +Parameters: + - Name: View + Type: System.String + Aliases: + + - Name: FilePath + Type: System.String + Aliases: + +Synopsis: Saves a Markdown Help Topic +Description: | + + Saves a Markdown Help Topic to a file. +--- + + +PowerShell.Markdown.Help.Save() +------------------------------- + + + + +### Synopsis +Saves a Markdown Help Topic + + + +--- + + +### Description + +Saves a Markdown Help Topic to a file. + + + +--- + + +### Related Links +* PowerShell.Markdown.Help.ToMarkdown + + + + + +--- + + +### Examples +> EXAMPLE 1 + +```PowerShell +(Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") +``` + + +--- + + +### Parameters +#### **FilePath** + +The path to the file. +If this does not exist it will be created. + + + + + + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[String]`|false |1 |false | + + + +#### **View** + +An optional view. +This would need to be declared in a .format.ps1xml file by another loaded module. + + + + + + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[String]`|false |2 |false | + + + + + +--- + + +### Notes +This will not save to files that have illegal names on Windows. + + + +--- From 078d256b8c5981515c03fff364aca293af208169 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:37:17 +0000 Subject: [PATCH 40/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- docs/PowerShell/Markdown/Help/ShowSection.md | 73 ++++++++++++++++++++ 1 file changed, 73 insertions(+) create mode 100644 docs/PowerShell/Markdown/Help/ShowSection.md diff --git a/docs/PowerShell/Markdown/Help/ShowSection.md b/docs/PowerShell/Markdown/Help/ShowSection.md new file mode 100644 index 00000000..684a92b0 --- /dev/null +++ b/docs/PowerShell/Markdown/Help/ShowSection.md @@ -0,0 +1,73 @@ +--- +CommandName: PowerShell.Markdown.Help.ShowSection +Parameters: + - Name: SectionNames + Type: System.String[] + Aliases: + - SectionName + +Synopsis: Shows sections of markdown help +Description: | + + Shows sections of a command's markdown help. +--- + + +PowerShell.Markdown.Help.ShowSection() +-------------------------------------- + + + + +### Synopsis +Shows sections of markdown help + + + +--- + + +### Description + +Shows sections of a command's markdown help. + + + +--- + + +### Parameters +#### **SectionNames** + +One or more section names + + + +Valid Values: + +* Name +* Synopsis +* Description +* RelatedLinks +* Examples +* Parameters +* Inputs +* Outputs +* Notes +* Story +* Syntax + + + + + + +|Type |Required|Position|PipelineInput|Aliases | +|------------|--------|--------|-------------|-----------| +|`[String[]]`|false |1 |false |SectionName| + + + + + +--- From fc04a688651ee675d7a1ba97693bbcfcd7b6fa25 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:37:17 +0000 Subject: [PATCH 41/53] Improving Extended Types Doc Generation Fixes #133 Fixes #135 --- docs/PowerShell/Markdown/Help/ToMarkdown.md | 68 +++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 docs/PowerShell/Markdown/Help/ToMarkdown.md diff --git a/docs/PowerShell/Markdown/Help/ToMarkdown.md b/docs/PowerShell/Markdown/Help/ToMarkdown.md new file mode 100644 index 00000000..b6f51133 --- /dev/null +++ b/docs/PowerShell/Markdown/Help/ToMarkdown.md @@ -0,0 +1,68 @@ +--- +CommandName: PowerShell.Markdown.Help.ToMarkdown +Parameters: + - Name: View + Type: System.String + Aliases: + +Synopsis: Returns this topic as a markdown string +Description: | + + Returns the content of this help topic as a markdown string. +--- + + +PowerShell.Markdown.Help.ToMarkdown() +------------------------------------- + + + + +### Synopsis +Returns this topic as a markdown string + + + +--- + + +### Description + +Returns the content of this help topic as a markdown string. + + + +--- + + +### Examples +> EXAMPLE 1 + +```PowerShell +(Get-MarkDownHelp Get-MarkDownHelp).ToMarkdown() +``` + + +--- + + +### Parameters +#### **View** + +An optional view. +This would need to be declared in a .format.ps1xml file by another loaded module. + + + + + + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[String]`|false |1 |false | + + + + + +--- From 6a1b80b3b1ee248f1eabd8dba02cdbce23f655c6 Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:40:04 -0700 Subject: [PATCH 42/53] Removing old doc files re #133 re #135 --- docs/PowerShell.Markdown.Help.HideSection.md | 73 ------------- docs/PowerShell.Markdown.Help.Save.md | 106 ------------------- docs/PowerShell.Markdown.Help.ShowSection.md | 73 ------------- docs/PowerShell.Markdown.Help.ToMarkdown.md | 68 ------------ 4 files changed, 320 deletions(-) delete mode 100644 docs/PowerShell.Markdown.Help.HideSection.md delete mode 100644 docs/PowerShell.Markdown.Help.Save.md delete mode 100644 docs/PowerShell.Markdown.Help.ShowSection.md delete mode 100644 docs/PowerShell.Markdown.Help.ToMarkdown.md diff --git a/docs/PowerShell.Markdown.Help.HideSection.md b/docs/PowerShell.Markdown.Help.HideSection.md deleted file mode 100644 index d7d845c6..00000000 --- a/docs/PowerShell.Markdown.Help.HideSection.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -CommandName: PowerShell.Markdown.Help.HideSection -Parameters: - - Name: SectionNames - Type: System.String[] - Aliases: - - SectionName - -Synopsis: Hides sections of markdown help -Description: | - - Hides sections of a command's markdown help. ---- - - -PowerShell.Markdown.Help.HideSection() --------------------------------------- - - - - -### Synopsis -Hides sections of markdown help - - - ---- - - -### Description - -Hides sections of a command's markdown help. - - - ---- - - -### Parameters -#### **SectionNames** - -One or more section names. - - - -Valid Values: - -* Name -* Synopsis -* Description -* RelatedLinks -* Examples -* Parameters -* Inputs -* Outputs -* Notes -* Story -* Syntax - - - - - - -|Type |Required|Position|PipelineInput|Aliases | -|------------|--------|--------|-------------|-----------| -|`[String[]]`|false |1 |false |SectionName| - - - - - ---- diff --git a/docs/PowerShell.Markdown.Help.Save.md b/docs/PowerShell.Markdown.Help.Save.md deleted file mode 100644 index 0028014a..00000000 --- a/docs/PowerShell.Markdown.Help.Save.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -CommandName: PowerShell.Markdown.Help.Save -Parameters: - - Name: View - Type: System.String - Aliases: - - - Name: FilePath - Type: System.String - Aliases: - -Synopsis: Saves a Markdown Help Topic -Description: | - - Saves a Markdown Help Topic to a file. ---- - - -PowerShell.Markdown.Help.Save() -------------------------------- - - - - -### Synopsis -Saves a Markdown Help Topic - - - ---- - - -### Description - -Saves a Markdown Help Topic to a file. - - - ---- - - -### Related Links -* PowerShell.Markdown.Help.ToMarkdown - - - - - ---- - - -### Examples -> EXAMPLE 1 - -```PowerShell -(Get-MarkdownHelp Get-MarkdownHelp).Save(".\test.md") -``` - - ---- - - -### Parameters -#### **FilePath** - -The path to the file. -If this does not exist it will be created. - - - - - - -|Type |Required|Position|PipelineInput| -|----------|--------|--------|-------------| -|`[String]`|false |1 |false | - - - -#### **View** - -An optional view. -This would need to be declared in a .format.ps1xml file by another loaded module. - - - - - - -|Type |Required|Position|PipelineInput| -|----------|--------|--------|-------------| -|`[String]`|false |2 |false | - - - - - ---- - - -### 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 deleted file mode 100644 index 684a92b0..00000000 --- a/docs/PowerShell.Markdown.Help.ShowSection.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -CommandName: PowerShell.Markdown.Help.ShowSection -Parameters: - - Name: SectionNames - Type: System.String[] - Aliases: - - SectionName - -Synopsis: Shows sections of markdown help -Description: | - - Shows sections of a command's markdown help. ---- - - -PowerShell.Markdown.Help.ShowSection() --------------------------------------- - - - - -### Synopsis -Shows sections of markdown help - - - ---- - - -### Description - -Shows sections of a command's markdown help. - - - ---- - - -### Parameters -#### **SectionNames** - -One or more section names - - - -Valid Values: - -* Name -* Synopsis -* Description -* RelatedLinks -* Examples -* Parameters -* Inputs -* Outputs -* Notes -* Story -* Syntax - - - - - - -|Type |Required|Position|PipelineInput|Aliases | -|------------|--------|--------|-------------|-----------| -|`[String[]]`|false |1 |false |SectionName| - - - - - ---- diff --git a/docs/PowerShell.Markdown.Help.ToMarkdown.md b/docs/PowerShell.Markdown.Help.ToMarkdown.md deleted file mode 100644 index b6f51133..00000000 --- a/docs/PowerShell.Markdown.Help.ToMarkdown.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -CommandName: PowerShell.Markdown.Help.ToMarkdown -Parameters: - - Name: View - Type: System.String - Aliases: - -Synopsis: Returns this topic as a markdown string -Description: | - - Returns the content of this help topic as a markdown string. ---- - - -PowerShell.Markdown.Help.ToMarkdown() -------------------------------------- - - - - -### Synopsis -Returns this topic as a markdown string - - - ---- - - -### Description - -Returns the content of this help topic as a markdown string. - - - ---- - - -### Examples -> EXAMPLE 1 - -```PowerShell -(Get-MarkDownHelp Get-MarkDownHelp).ToMarkdown() -``` - - ---- - - -### Parameters -#### **View** - -An optional view. -This would need to be declared in a .format.ps1xml file by another loaded module. - - - - - - -|Type |Required|Position|PipelineInput| -|----------|--------|--------|-------------| -|`[String]`|false |1 |false | - - - - - ---- From 7a1993ea3c0d91cff2e6347e305574ba5914b9ac Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:41:40 -0700 Subject: [PATCH 43/53] Updating links to Microsoft modules (Fixes #142) --- Formatting/PowerShell.Markdown.Help.format.ps1 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Formatting/PowerShell.Markdown.Help.format.ps1 b/Formatting/PowerShell.Markdown.Help.format.ps1 index 6db0a8fb..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) { From b692ecef7de39e6d8889eb997041378728c4c80d Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:42:27 +0000 Subject: [PATCH 44/53] Updating links to Microsoft modules (Fixes #142) --- HelpOut.format.ps1xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/HelpOut.format.ps1xml b/HelpOut.format.ps1xml index 9106ee35..85fc3cc4 100644 --- a/HelpOut.format.ps1xml +++ b/HelpOut.format.ps1xml @@ -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) { From e8dafb8a8342b86331b37c8efdd323fe2367ef54 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:42:34 +0000 Subject: [PATCH 45/53] Updating links to Microsoft modules (Fixes #142) --- docs/Get-MAML.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Get-MAML.md b/docs/Get-MAML.md index 1c535c48..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) From 818d5e6bbbafb5675118969a3af3658ebe01ea01 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:42:35 +0000 Subject: [PATCH 46/53] Updating links to Microsoft modules (Fixes #142) --- docs/Get-MarkdownHelp.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Get-MarkdownHelp.md b/docs/Get-MarkdownHelp.md index 2ff4d9a5..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) From c4a384a6e975dc176091fb2e336d8e237eb8b3ea Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:42:35 +0000 Subject: [PATCH 47/53] Updating links to Microsoft modules (Fixes #142) --- docs/Measure-Help.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Measure-Help.md b/docs/Measure-Help.md index 5921a6de..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) From 269be97f33cf17d879fbd028c8f4bafc915df2a0 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:42:36 +0000 Subject: [PATCH 48/53] Updating links to Microsoft modules (Fixes #142) --- docs/ConvertTo-MAML.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ConvertTo-MAML.md b/docs/ConvertTo-MAML.md index 1c535c48..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) From 710c18a81432adc83426dcc505d5b54139e6c6dc Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:53:03 -0700 Subject: [PATCH 49/53] Integrating PSA into HelpOut (Fixes #144) --- .github/workflows/TestReleaseAndPublish.yml | 3 ++ GitHub/Jobs/BuildHelpOut.psd1 | 8 +++- HelpOut.PSA.ps1 | 47 +++++++++++++++++++++ 3 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 HelpOut.PSA.ps1 diff --git a/.github/workflows/TestReleaseAndPublish.yml b/.github/workflows/TestReleaseAndPublish.yml index 41029f27..6d48bcc6 100644 --- a/.github/workflows/TestReleaseAndPublish.yml +++ b/.github/workflows/TestReleaseAndPublish.yml @@ -590,4 +590,7 @@ jobs: if: ${{github.ref_name != 'master'}} uses: ./ id: HelpOutBranch + - name: PSA + uses: StartAutomating/PSA@main + id: PSA 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.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 From d9865c19d526bdda154470cb62ca8e80e4f8000b Mon Sep 17 00:00:00 2001 From: James Brundage <@github.com> Date: Tue, 19 Sep 2023 20:58:44 -0700 Subject: [PATCH 50/53] Updating Module Version [0.4.8] and CHANGELOG --- CHANGELOG.md | 17 +++++++++++++++++ HelpOut.psd1 | 18 ++++++++++++++---- 2 files changed, 31 insertions(+), 4 deletions(-) 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/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) --- From 9b20c93758367868852297fdea2391d6648ea2be Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:59:53 +0000 Subject: [PATCH 51/53] Updating Module Version [0.4.8] and CHANGELOG --- docs/CHANGELOG.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) 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) From fc68df6ecc0c223fee3f28f5d179c6655fd9cbf5 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:59:54 +0000 Subject: [PATCH 52/53] Updating Module Version [0.4.8] and CHANGELOG --- HelpOut-Help.xml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) 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. From 57394789bb3483f765701aefb50763475c9158f9 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Wed, 20 Sep 2023 03:59:54 +0000 Subject: [PATCH 53/53] Updating Module Version [0.4.8] and CHANGELOG Fixing PSA credentials (Fixes #144) --- .github/workflows/TestReleaseAndPublish.yml | 4 +++- HelpOut-Help.xml | 16 ++++++++-------- HelpOut.GitHubWorkflow.PSDevOps.ps1 | 5 ++++- 3 files changed, 15 insertions(+), 10 deletions(-) diff --git a/.github/workflows/TestReleaseAndPublish.yml b/.github/workflows/TestReleaseAndPublish.yml index 6d48bcc6..a70eff9e 100644 --- a/.github/workflows/TestReleaseAndPublish.yml +++ b/.github/workflows/TestReleaseAndPublish.yml @@ -593,4 +593,6 @@ jobs: - 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/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