From 55dfbda9c6f9125cb1bb85c649525430a9b00a27 Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 09:33:03 -0700 Subject: [PATCH 01/45] fix: HelpOut Extended Member Summary Titling ( Fixes #202 ) --- ...HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 | 40 +++++++++++++++---- 1 file changed, 32 insertions(+), 8 deletions(-) diff --git a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 index 60a1a107..5ffd24d6 100644 --- a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 +++ b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 @@ -35,7 +35,12 @@ $punctuationNotDashOrUnderscore = '[\p{P}-[\-_]]' # go over each extended type foreach ($extendedType in $extendedTypeNames) { # and get the actual type data - $actualTypeData = Get-TypeData -TypeName $extendedType + $actualTypeData = Get-TypeData -TypeName $extendedType + + # We will want to keep track of methods and properties in order, + # so we don't have to sort or resolve them later. + $methodsByName = [Ordered]@{} + $propertiesByName = [Ordered]@{} $memberFiles = @(foreach ($member in $actualTypeData.Members.Values) { @@ -81,9 +86,22 @@ foreach ($extendedType in $extendedTypeNames) { ).md" # .Save it, - $markdownHelp.Save($etsDocPath) - # and remove the temporary function (it would have gone out of scope anyways) + $memberFile = $markdownHelp.Save($etsDocPath) + # and remove the temporary function (it would have gone out of scope anyways). $ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)") + + # Emit the member file + $memberFile + + if ($getSetNothing) { + if (-not $propertiesByName[$member.Name]) { + $propertiesByName[$member.Name] = $memberFile + } else { + $propertiesByName[$member.Name] = @($propertiesByName[$member.Name]) + $memberFile + } + } else { + $methodsByName[$member.Name] = $memberFile + } } @@ -119,21 +137,27 @@ foreach ($extendedType in $extendedTypeNames) { "### Script Properties" [Environment]::NewLine # and be sorted by property name. - foreach ($memberFile in $propertyMemberFiles | Sort-Object { $_.Name -replace $getSetFile}) { - "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))" + foreach ($memberKeyValue in $propertiesByName.GetEnumerator()) { + # If there are multiple files for a property, it's got a get and a set. + if ($memberKeyValue.Value -is [array]) { + "* [get_$($memberKeyValue.Key)]($($memberKeyValue.Value[0].Name))" + "* [set_$($memberKeyValue.Key)]($($memberKeyValue.Value[1].Name))" + } else { + "* [get_$($memberKeyValue.Key)]($($memberKeyValue.Value.Name))" + } } + [Environment]::NewLine } # Methods should come after properties. if ($methodMemberFiles) { "### Script Methods" [Environment]::NewLine # and will be sorted alphabetically. - foreach ($memberFile in $methodMemberFiles) { - "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))" + foreach ($memberKeyValue in $methodsByName.GetEnumerator()) { + "* [$($memberKeyValue.Key)()]($($memberKeyValue.Value.Name))" } } } - ) -join ([Environment]::NewLine) $ExtendedTypeDocContent | Set-Content -Path $ExtendedTypeDocFile From 984ce9a779237166408423f8034d639019d7aab6 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 16:34:26 +0000 Subject: [PATCH 02/45] fix: HelpOut Extended Member Summary Titling ( Fixes #202 ) --- docs/PowerShell/Markdown/Help/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/PowerShell/Markdown/Help/README.md b/docs/PowerShell/Markdown/Help/README.md index 12d67e2c..d415226e 100644 --- a/docs/PowerShell/Markdown/Help/README.md +++ b/docs/PowerShell/Markdown/Help/README.md @@ -4,7 +4,7 @@ ### Script Methods -* [HideSection](HideSection.md) -* [Save](Save.md) -* [ShowSection](ShowSection.md) -* [ToMarkdown](ToMarkdown.md) +* [HideSection()](HideSection.md) +* [Save()](Save.md) +* [ShowSection()](ShowSection.md) +* [ToMarkdown()](ToMarkdown.md) From 0235c918c218e0c9a30be35ab71afe0da54ba075 Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 09:41:36 -0700 Subject: [PATCH 03/45] docs: PowerShell.Markdown.Help.README --- Types/PowerShell.Markdown.Help/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) create mode 100644 Types/PowerShell.Markdown.Help/README.md diff --git a/Types/PowerShell.Markdown.Help/README.md b/Types/PowerShell.Markdown.Help/README.md new file mode 100644 index 00000000..616fec52 --- /dev/null +++ b/Types/PowerShell.Markdown.Help/README.md @@ -0,0 +1,8 @@ +This PSType is used to transform help for a command into Markdown. + +To get help for any command as markdown, use `Get-MarkdownHelp`. + +~~~PowerShell +$MarkdownHelp = Get-MarkdownHelp Get-MarkdownHelp +$MarkdownHelp +~~~ \ No newline at end of file From 2712a01fe6b8908f70e8dd5af3daf2bb091b1b3d Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 16:42:33 +0000 Subject: [PATCH 04/45] docs: PowerShell.Markdown.Help.README --- HelpOut.types.ps1xml | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index b383fc89..848a2fd9 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -137,6 +137,17 @@ $View = 'PowerShell.Markdown.Help' Out-String -Width 1mb).Trim() + + README + This PSType is used to transform help for a command into Markdown. + +To get help for any command as markdown, use `Get-MarkdownHelp`. + +~~~PowerShell +$MarkdownHelp = Get-MarkdownHelp Get-MarkdownHelp +$MarkdownHelp +~~~ + From 3ada6463d5bf10c6a23d5bd2bcf3fce85a185205 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 16:42:42 +0000 Subject: [PATCH 05/45] docs: PowerShell.Markdown.Help.README --- docs/PowerShell/Markdown/Help/README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/PowerShell/Markdown/Help/README.md b/docs/PowerShell/Markdown/Help/README.md index d415226e..f4562fb4 100644 --- a/docs/PowerShell/Markdown/Help/README.md +++ b/docs/PowerShell/Markdown/Help/README.md @@ -1,6 +1,14 @@ ## PowerShell.Markdown.Help +This PSType is used to transform help for a command into Markdown. + +To get help for any command as markdown, use `Get-MarkdownHelp`. + +~~~PowerShell +$MarkdownHelp = Get-MarkdownHelp Get-MarkdownHelp +$MarkdownHelp +~~~ ### Script Methods From 08b3d384021f1a37230f02eb1b8dce0f13122e45 Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 09:59:32 -0700 Subject: [PATCH 06/45] fix: HelpOut Extended Member Summary Titling ( Fixes #202 ) Adding newline below README --- Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 | 1 + 1 file changed, 1 insertion(+) diff --git a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 index 5ffd24d6..73401a9d 100644 --- a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 +++ b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 @@ -124,6 +124,7 @@ foreach ($extendedType in $extendedTypeNames) { # If the type had a .README member, include it inline if ($actualTypeData.Members -and $actualTypeData.Members["README"].Value) { $actualTypeData.Members["README"].Value + [Environment]::NewLine } # Sort the member files into properties and methods From 39151b1e3bb753318b9d5bf5e647169bd3e9856c Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 17:00:36 +0000 Subject: [PATCH 07/45] fix: HelpOut Extended Member Summary Titling ( Fixes #202 ) Adding newline below README --- docs/PowerShell/Markdown/Help/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/PowerShell/Markdown/Help/README.md b/docs/PowerShell/Markdown/Help/README.md index f4562fb4..59714f3c 100644 --- a/docs/PowerShell/Markdown/Help/README.md +++ b/docs/PowerShell/Markdown/Help/README.md @@ -9,6 +9,8 @@ To get help for any command as markdown, use `Get-MarkdownHelp`. $MarkdownHelp = Get-MarkdownHelp Get-MarkdownHelp $MarkdownHelp ~~~ + + ### Script Methods From 6ff46cb842f6a20af98bc804a4ad3579f8975eef Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 14:52:30 -0700 Subject: [PATCH 08/45] feat: Script Properties should be in separate files ( Fixes #203 ) --- Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 index 73401a9d..4bd3a7d3 100644 --- a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 +++ b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 @@ -79,7 +79,11 @@ foreach ($extendedType in $extendedTypeNames) { $TopicPathSegments = @( $extendedType -split $punctuationNotDashOrUnderscore - $member.Name -replace $replaceMostPunctuation + if ($getSetNothing) { + $getSetNothing + ($member.Name -replace $replaceMostPunctuation) + } else { + $member.Name -replace $replaceMostPunctuation + } ) $etsDocPath = Join-Path $outputPath "$( $TopicPathSegments -join [IO.Path]::DirectorySeparatorChar From 710312019245e5748d1b3b37a0967e4814d3ae96 Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 15:10:50 -0700 Subject: [PATCH 09/45] feat: HelpInfo.ToJson ( Fixes #205 ) --- Types/HelpInfo/ToJson.ps1 | 84 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 Types/HelpInfo/ToJson.ps1 diff --git a/Types/HelpInfo/ToJson.ps1 b/Types/HelpInfo/ToJson.ps1 new file mode 100644 index 00000000..d8dda563 --- /dev/null +++ b/Types/HelpInfo/ToJson.ps1 @@ -0,0 +1,84 @@ +<# +.SYNOPSIS + Convert HelpInfo to json +.DESCRIPTION + Converts a HelpInfo object to a JSON representation of the object. +.EXAMPLE + (Get-Help Get-Help).ToJson() +#> + +param() + +$helpObject = $this +[Ordered]@{ + Synopsis = $helpObject.Synopsis + Description = $helpObject.Description.text -join ([Environment]::NewLine * 2) + Parameters = @(foreach ($parameter in $helpObject.Parameters) { + [Ordered]@{ + Name = $parameter.Name + Type = $parameter.Type.Name + Description = $parameter.Description.text -join ([Environment]::NewLine * 2) + Required = $parameter.Required -match $true + Position = if ($null -ne ($parameter.Position -as [int])) { + $parameter.Position -as [int] + } else { + -1 + } + Aliases = $parameter.Aliases + DefaultValue = $parameter.DefaultValue + Globbing = $parameter.Globbing -match $true + PipelineInput = $parameter.PipelineInput + variableLength = $parameter.variableLength -match $true + } + }) + Notes = @($helpObject.alertSet.alert.text) + CommandType = $helpObject.Category + Component = @($helpObject.Component) + Inputs = @( + $helpObject.InputTypes.InputType.Type.Name + ) + Outputs = @( + $helpObject.ReturnValues.ReturnValue.Type.Name + ) + Links = @( + foreach ($relLink in $this.RelatedLinks.navigationLink) { + if ($relLink.uri) { + $relLink.uri + } else { + $relLink.text + } + } + ) + Examples = @( + foreach ($example in $helpObject.Examples.Example) { + # 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 + [Ordered]@{ + Title = ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') + Markdown = $markdownLines -join [Environment]::NewLine + Code = $codeBlock + } + } + ) +} | ConvertTo-Json -Depth 10 \ No newline at end of file From 42f60fd29d2781d9cc462b3993d70ed66d0f43b4 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:11:34 +0000 Subject: [PATCH 10/45] feat: HelpInfo.ToJson ( Fixes #205 ) --- HelpOut.types.ps1xml | 94 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 94 insertions(+) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 848a2fd9..12cf3e45 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -1,6 +1,100 @@ + + HelpInfo + + + ToJson + + + + PowerShell.Markdown.Help From 30d30e343ea3d9f89ccce97bbdfca06693706bd9 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:11:42 +0000 Subject: [PATCH 11/45] feat: HelpInfo.ToJson ( Fixes #205 ) --- docs/HelpInfo/README.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 docs/HelpInfo/README.md diff --git a/docs/HelpInfo/README.md b/docs/HelpInfo/README.md new file mode 100644 index 00000000..ac0d53d5 --- /dev/null +++ b/docs/HelpInfo/README.md @@ -0,0 +1,7 @@ +## HelpInfo + + +### Script Methods + + +* [ToJson()](ToJson.md) From d3a75005fc3448d0311175f9e9d6aecbfb411179 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:11:42 +0000 Subject: [PATCH 12/45] feat: HelpInfo.ToJson ( Fixes #205 ) --- docs/HelpInfo/ToJson.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/HelpInfo/ToJson.md diff --git a/docs/HelpInfo/ToJson.md b/docs/HelpInfo/ToJson.md new file mode 100644 index 00000000..2d7f6564 --- /dev/null +++ b/docs/HelpInfo/ToJson.md @@ -0,0 +1,22 @@ +HelpInfo.ToJson() +----------------- + +### Synopsis +Convert HelpInfo to json + +--- + +### Description + +Converts a HelpInfo object to a JSON representation of the object. + +--- + +### Examples +> EXAMPLE 1 + +```PowerShell +(Get-Help Get-Help).ToJson() +``` + +--- From 5dddfcf1a7e237522c400326e0b2c154a5cbe56e Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 15:13:27 -0700 Subject: [PATCH 13/45] feat: HelpInfo.get_Note ( Fixes #206 ) --- Types/HelpInfo/Alias.psd1 | 3 +++ Types/HelpInfo/get_Note.ps1 | 11 +++++++++++ 2 files changed, 14 insertions(+) create mode 100644 Types/HelpInfo/Alias.psd1 create mode 100644 Types/HelpInfo/get_Note.ps1 diff --git a/Types/HelpInfo/Alias.psd1 b/Types/HelpInfo/Alias.psd1 new file mode 100644 index 00000000..a40eb80b --- /dev/null +++ b/Types/HelpInfo/Alias.psd1 @@ -0,0 +1,3 @@ +@{ + Notes = 'Note' +} \ No newline at end of file diff --git a/Types/HelpInfo/get_Note.ps1 b/Types/HelpInfo/get_Note.ps1 new file mode 100644 index 00000000..8c2a908e --- /dev/null +++ b/Types/HelpInfo/get_Note.ps1 @@ -0,0 +1,11 @@ +<# +.SYNOPSIS + Gets HelpInfo notes +.DESCRIPTION + Gets the `Notes` section of a HelpInfo object. +.EXAMPLE + (Get-Help Get-Help).Note +#> +param() + +@($this.alertSet.alert.text) \ No newline at end of file From 8b4ea6f907d1dadddb12366d1d6e5cbe85224014 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:14:12 +0000 Subject: [PATCH 14/45] feat: HelpInfo.get_Note ( Fixes #206 ) --- HelpOut.types.ps1xml | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 12cf3e45..41eef57b 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -4,6 +4,10 @@ HelpInfo + + Notes + Note + ToJson + + Note + + <# +.SYNOPSIS + Gets HelpInfo notes +.DESCRIPTION + Gets the `Notes` section of a HelpInfo object. +.EXAMPLE + (Get-Help Get-Help).Note +#> +param() + +@($this.alertSet.alert.text) + + From 307f36a7170738cf8ee9cbc52490ff55ae6ba375 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:14:20 +0000 Subject: [PATCH 15/45] feat: HelpInfo.get_Note ( Fixes #206 ) --- docs/HelpInfo/README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/HelpInfo/README.md b/docs/HelpInfo/README.md index ac0d53d5..fa498285 100644 --- a/docs/HelpInfo/README.md +++ b/docs/HelpInfo/README.md @@ -1,6 +1,12 @@ ## HelpInfo +### Script Properties + + +* [get_Note](get_Note.md) + + ### Script Methods From 66cdd463a878d21b60a4416057f75658d0b7c67f Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:14:21 +0000 Subject: [PATCH 16/45] feat: HelpInfo.get_Note ( Fixes #206 ) --- docs/HelpInfo/get_Note.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 docs/HelpInfo/get_Note.md diff --git a/docs/HelpInfo/get_Note.md b/docs/HelpInfo/get_Note.md new file mode 100644 index 00000000..81458676 --- /dev/null +++ b/docs/HelpInfo/get_Note.md @@ -0,0 +1,22 @@ +get_Note +-------- + +### Synopsis +Gets HelpInfo notes + +--- + +### Description + +Gets the `Notes` section of a HelpInfo object. + +--- + +### Examples +> EXAMPLE 1 + +```PowerShell +(Get-Help Get-Help).Note +``` + +--- From 9839137a489bf76d49bdee7912f059e7b827a3b0 Mon Sep 17 00:00:00 2001 From: James Brundage <+@noreply.github.com> Date: Sun, 13 Oct 2024 15:23:54 -0700 Subject: [PATCH 17/45] feat: HelpInfo.SaveJson ( Fixes #207 ) --- Types/HelpInfo/SaveJson.ps1 | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 Types/HelpInfo/SaveJson.ps1 diff --git a/Types/HelpInfo/SaveJson.ps1 b/Types/HelpInfo/SaveJson.ps1 new file mode 100644 index 00000000..75feebee --- /dev/null +++ b/Types/HelpInfo/SaveJson.ps1 @@ -0,0 +1,30 @@ +<# +.SYNOPSIS + Saves a Help Topic as json +.DESCRIPTION + Saves a Help Topic to a json file. +.NOTES + This will not save to files that have illegal names on Windows. +.EXAMPLE + (Get-MarkdownHelp Get-MarkdownHelp).SaveJson(".\test.json") +.LINK + HelpInfo.ToJson +#> +param( +# The path to the file. +# If this does not exist it will be created. +[string] +$FilePath +) + +$illegalCharacters = @('<', '>', '|', '?', '*', ':') +$illegalCharacterRegex = '[' + ($illegalCharacters | Foreach-Object { [regex]::Escape($_) }) + ']' +$illegalCharacterReadable = ($illegalCharacters | Foreach-Object { "`"$_`"" }) -join ', ' + +$filePathWithoutQualifier = Split-Path $filePath -NoQualifier +if ($filePathWithoutQualifier -match $illegalCharacterRegex) { + Write-Warning "Will not .Save to $filePath, because that path will not be readable on all operating systems. It cannot contain any of the characters $illegalCharacterReadable." + return +} + +New-Item -ItemType File -Path $FilePath -Force -Value $this.ToJson() From 3a252d33a832a5d6e9b8d1e8b278e279af647ae3 Mon Sep 17 00:00:00 2001 From: StartAutomating Date: Sun, 13 Oct 2024 22:24:48 +0000 Subject: [PATCH 18/45] feat: HelpInfo.SaveJson ( Fixes #207 ) --- HelpOut.types.ps1xml | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 41eef57b..45d72bbc 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -8,6 +8,42 @@ Notes Note + + SaveJson + + ToJson