diff --git a/CHANGELOG.md b/CHANGELOG.md index a658aaf4..ac5d3a2f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,18 @@ +### HelpOut 0.5.5: + +* Save-MarkdownHelp `-JsonDataPath/-NoJson` (#208, #179) +* Extending `HelpInfo`: + * `HelpInfo.ToJson` (#205) + * `HelpInfo.get_Note` (#206) + * `HelpInfo.SaveJson` (#207) +* Extended Type Help Improvements: + * Fixing Summary Titles (#202) + * Separating Script Properties (#203) +* Special Thanks: + * @potatoqualitee + +--- + ### HelpOut 0.5.4: * HelpOut containerization diff --git a/Commands/Save-MarkdownHelp.ps1 b/Commands/Save-MarkdownHelp.ps1 index a7c9f581..a81a64b4 100644 --- a/Commands/Save-MarkdownHelp.ps1 +++ b/Commands/Save-MarkdownHelp.ps1 @@ -162,7 +162,17 @@ # If the value is a [string], it will be expanded # In either context, `$_` will be the current attribute. [PSObject] - $FormatAttribute + $FormatAttribute, + + # The path where json data should be located. + # If this is not provided, it will be assumed to be a subdirectory of the -OutputPath. + # Specifically, it will be assumed to be: `$OutputPath/_data/Help` + [string] + $JsonDataPath, + + # If set, will not output json data files. + [switch] + $NoJson ) begin { @@ -252,6 +262,12 @@ $null = New-Item -ItemType Directory -Path $OutputPath # create it. } + if (-not $PSBoundParameters.JsonDataPath) { + $JsonDataPath = Join-Path $OutputPath '_data' | Join-Path -ChildPath 'Help' + } else { + $JsonDataPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($JsonDataPath) + } + if ((-not $ExcludeSubModule) -and (-not $IncludeSubmodule)) { Push-Location $theModuleRoot @@ -291,6 +307,9 @@ # Determine the output path for each item. $docOutputPath = Join-Path $outputPath ($cmd.Name + '.md') + if ($JsonDataPath) { + $jsonOutputPath = Join-Path $JsonDataPath ($cmd.Name + '.json') + } # Prepare a splat for this command by copying out base splat. $getMarkdownHelpSplat = @{Name="$cmd"} + $getMarkdownHelpSplatBase @@ -298,8 +317,9 @@ if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki } # otherwise, pass down the parent of $OutputPath. else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"} - - $markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat + + $markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat + $markdownFile = if ($markdownTopic.Save) { $markdownTopic.Save($docOutputPath) @@ -312,6 +332,20 @@ $markdownFile } } + if ($JsonDataPath -and -not $NoJson) { + $jsonFile = + if ($markdownTopic.SaveJson) { + $markdownTopic.SaveJson($jsonOutputPath) + } else { $null } + + if ($jsonFile) { + $filesChanged += $jsonFile + + if ($PassThru) { # If -PassThru was provided, get the path. + $jsonFile + } + } + } } if ($Command) { diff --git a/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 b/Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1 index 60a1a107..4bd3a7d3 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) { @@ -74,16 +79,33 @@ 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 ).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 + } } @@ -106,6 +128,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 @@ -119,21 +142,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 diff --git a/HelpOut-Help.xml b/HelpOut-Help.xml index bfcd951d..1f03b4df 100644 --- a/HelpOut-Help.xml +++ b/HelpOut-Help.xml @@ -8,7 +8,7 @@ Gets MAML help - 0.5.4 + 0.5.5 Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml. @@ -535,7 +535,7 @@ If not provided, all types of commands from the module will be saved as a markdo Gets Markdown Help - 0.5.4 + 0.5.5 Gets Help for a given command, in Markdown @@ -838,7 +838,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Gets a script's references - 0.5.4 + 0.5.5 Gets the external references of a given PowerShell command. These are the commands the script calls, and the types the script uses. @@ -964,7 +964,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Gets a Script's story - 0.5.4 + 0.5.5 Gets the Script's "Story" @@ -1127,7 +1127,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Installs MAML into a module - 0.5.4 + 0.5.5 Installs MAML into a module. @@ -1563,7 +1563,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Determines the percentage of documentation - 0.5.4 + 0.5.5 Determines the percentage of documentation in a given script @@ -1706,7 +1706,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Saves a Module's MAML - 0.5.4 + 0.5.5 Generates a Module's MAML file, and then saves it to the appropriate location. @@ -2048,7 +2048,7 @@ If not provided, all types of commands from the module will be saved as a markdo Saves a Module's Markdown Help - 0.5.4 + 0.5.5 Get markdown help for each command in a module and saves it to the appropriate location. @@ -2414,6 +2414,34 @@ In either context, `$_` will be the current attribute. + + JsonDataPath + + The path where json data should be located. +If this is not provided, it will be assumed to be a subdirectory of the -OutputPath. +Specifically, it will be assumed to be: `$OutputPath/_data/Help` + + String + + String + + + + + + + NoJson + + If set, will not output json data files. + + Switch + + Switch + + + + + @@ -2574,6 +2602,21 @@ By default ```\.help\.txt$``` and ```\.md$``` + + JsonDataPath + + The path where json data should be located. +If this is not provided, it will be assumed to be a subdirectory of the -OutputPath. +Specifically, it will be assumed to be: `$OutputPath/_data/Help` + + String + + String + + + + + Module @@ -2587,6 +2630,19 @@ By default ```\.help\.txt$``` and ```\.md$``` + + NoJson + + If set, will not output json data files. + + Switch + + Switch + + + + + NoValidValueEnumeration diff --git a/HelpOut.psd1 b/HelpOut.psd1 index 836a0ded..96c9df0a 100644 --- a/HelpOut.psd1 +++ b/HelpOut.psd1 @@ -7,32 +7,26 @@ ModuleToProcess='HelpOut.psm1' FormatsToProcess='HelpOut.format.ps1xml' TypesToProcess='HelpOut.types.ps1xml' - ModuleVersion='0.5.4' + ModuleVersion='0.5.5' PrivateData = @{ PSData = @{ ProjectURI = 'https://github.com/StartAutomating/HelpOut' LicenseURI = 'https://github.com/StartAutomating/HelpOut/blob/master/LICENSE' - Tags = 'Markdown', 'Help','PowerShell' + Tags = 'Markdown', 'Help', 'PowerShell' ReleaseNotes = @' -### HelpOut 0.5.4: +### HelpOut 0.5.5: -* HelpOut containerization - * Dockerfile (#182) - * Publishing to `https://ghcr.io/startautomating/helpout` (#183) - * Container.init.ps1 (#191) - * Container.start.ps1 (#193) - * Container.stop.ps1 (#194) -* Get/Save-Maml -IncludeAlias/-SkipCommandType (#178) (thanks @potatoqualitee ! ) -* Get-MarkdownHelp keeps alias names (#200) -* HelpOut repository improvements - * Organizing Files (#184, #185, #186, #187) -* HelpOut is now exported as `$HelpOut` (#188) -* HelpOut's root is now exported as `HelpOut:` (#189) -* Extended Type Help Improvement: - * Extended Member Titles (#198) - * Fixing Grouping (#197) - * Fixing Type File Naming (#196) +* Save-MarkdownHelp `-JsonDataPath/-NoJson` (#208, #179) +* Extending `HelpInfo`: + * `HelpInfo.ToJson` (#205) + * `HelpInfo.get_Note` (#206) + * `HelpInfo.SaveJson` (#207) +* Extended Type Help Improvements: + * Fixing Summary Titles (#202) + * Separating Script Properties (#203) +* Special Thanks: + * @potatoqualitee --- diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index b383fc89..45d72bbc 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -1,6 +1,156 @@ + + HelpInfo + + + Notes + Note + + + SaveJson + + + + 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) + + + + PowerShell.Markdown.Help @@ -137,6 +287,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 +~~~ + 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/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() 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 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 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 diff --git a/allcommands.ps1 b/allcommands.ps1 index 225b6d8b..ff5dc7e8 100644 --- a/allcommands.ps1 +++ b/allcommands.ps1 @@ -1576,7 +1576,17 @@ function Save-MarkdownHelp # If the value is a [string], it will be expanded # In either context, `$_` will be the current attribute. [PSObject] - $FormatAttribute + $FormatAttribute, + + # The path where json data should be located. + # If this is not provided, it will be assumed to be a subdirectory of the -OutputPath. + # Specifically, it will be assumed to be: `$OutputPath/_data/Help` + [string] + $JsonDataPath, + + # If set, will not output json data files. + [switch] + $NoJson ) begin { @@ -1666,6 +1676,12 @@ function Save-MarkdownHelp $null = New-Item -ItemType Directory -Path $OutputPath # create it. } + if (-not $PSBoundParameters.JsonDataPath) { + $JsonDataPath = Join-Path $OutputPath '_data' | Join-Path -ChildPath 'Help' + } else { + $JsonDataPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($JsonDataPath) + } + if ((-not $ExcludeSubModule) -and (-not $IncludeSubmodule)) { Push-Location $theModuleRoot @@ -1705,6 +1721,9 @@ function Save-MarkdownHelp # Determine the output path for each item. $docOutputPath = Join-Path $outputPath ($cmd.Name + '.md') + if ($JsonDataPath) { + $jsonOutputPath = Join-Path $JsonDataPath ($cmd.Name + '.json') + } # Prepare a splat for this command by copying out base splat. $getMarkdownHelpSplat = @{Name="$cmd"} + $getMarkdownHelpSplatBase @@ -1712,8 +1731,9 @@ function Save-MarkdownHelp if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki } # otherwise, pass down the parent of $OutputPath. else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"} - - $markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat + + $markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat + $markdownFile = if ($markdownTopic.Save) { $markdownTopic.Save($docOutputPath) @@ -1726,6 +1746,20 @@ function Save-MarkdownHelp $markdownFile } } + if ($JsonDataPath -and -not $NoJson) { + $jsonFile = + if ($markdownTopic.SaveJson) { + $markdownTopic.SaveJson($jsonOutputPath) + } else { $null } + + if ($jsonFile) { + $filesChanged += $jsonFile + + if ($PassThru) { # If -PassThru was provided, get the path. + $jsonFile + } + } + } } if ($Command) { diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index ad2425e2..e4e8df5f 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,3 +1,18 @@ +### HelpOut 0.5.5: + +* Save-MarkdownHelp `-JsonDataPath/-NoJson` (#208, #179) +* Extending `HelpInfo`: + * `HelpInfo.ToJson` (#205) + * `HelpInfo.get_Note` (#206) + * `HelpInfo.SaveJson` (#207) +* Extended Type Help Improvements: + * Fixing Summary Titles (#202) + * Separating Script Properties (#203) +* Special Thanks: + * @potatoqualitee + +--- + ### HelpOut 0.5.4: * HelpOut containerization diff --git a/docs/HelpInfo/README.md b/docs/HelpInfo/README.md new file mode 100644 index 00000000..f5f12cf0 --- /dev/null +++ b/docs/HelpInfo/README.md @@ -0,0 +1,14 @@ +## HelpInfo + + +### Script Properties + + +* [get_Note](get_Note.md) + + +### Script Methods + + +* [SaveJson()](SaveJson.md) +* [ToJson()](ToJson.md) diff --git a/docs/HelpInfo/SaveJson.md b/docs/HelpInfo/SaveJson.md new file mode 100644 index 00000000..1d5631ad --- /dev/null +++ b/docs/HelpInfo/SaveJson.md @@ -0,0 +1,43 @@ +HelpInfo.SaveJson() +------------------- + +### Synopsis +Saves a Help Topic as json + +--- + +### Description + +Saves a Help Topic to a json file. + +--- + +### Related Links +* HelpInfo.ToJson + +--- + +### Examples +> EXAMPLE 1 + +```PowerShell +(Get-MarkdownHelp Get-MarkdownHelp).SaveJson(".\test.json") +``` + +--- + +### Parameters +#### **FilePath** +The path to the file. +If this does not exist it will be created. + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[String]`|false |1 |false | + +--- + +### Notes +This will not save to files that have illegal names on Windows. + +--- 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() +``` + +--- 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 +``` + +--- diff --git a/docs/PowerShell/Markdown/Help/README.md b/docs/PowerShell/Markdown/Help/README.md index 12d67e2c..59714f3c 100644 --- a/docs/PowerShell/Markdown/Help/README.md +++ b/docs/PowerShell/Markdown/Help/README.md @@ -1,10 +1,20 @@ ## 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 -* [HideSection](HideSection.md) -* [Save](Save.md) -* [ShowSection](ShowSection.md) -* [ToMarkdown](ToMarkdown.md) +* [HideSection()](HideSection.md) +* [Save()](Save.md) +* [ShowSection()](ShowSection.md) +* [ToMarkdown()](ToMarkdown.md) diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index 91500951..cda93233 100644 --- a/docs/Save-MarkdownHelp.md +++ b/docs/Save-MarkdownHelp.md @@ -250,9 +250,25 @@ In either context, `$_` will be the current attribute. |------------|--------|--------|-------------| |`[PSObject]`|false |named |false | +#### **JsonDataPath** +The path where json data should be located. +If this is not provided, it will be assumed to be a subdirectory of the -OutputPath. +Specifically, it will be assumed to be: `$OutputPath/_data/Help` + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[String]`|false |named |false | + +#### **NoJson** +If set, will not output json data files. + +|Type |Required|Position|PipelineInput| +|----------|--------|--------|-------------| +|`[Switch]`|false |named |false | + --- ### Syntax ```PowerShell -Save-MarkdownHelp [-Module ] [-OutputPath ] [-Wiki] [-Command ] [-ReplaceCommandName ] [-ReplaceCommandNameWith ] [-ScriptPath ] [-ReplaceScriptName ] [-ReplaceScriptNameWith ] [-ReplaceLink ] [-ReplaceLinkWith ] [-PassThru] [-SectionOrder ] [-IncludeTopic ] [-ExcludeTopic ] [-ExcludeFile ] [-IncludeFile ] [-IncludeExtension ] [-ExcludeExtension ] [-IncludeSubmodule] [-ExcludeSubModule] [-NoValidValueEnumeration] [-IncludeYamlHeader] [-YamlHeaderInformationType ] [-SkipCommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Script | Configuration | All}] [-FormatAttribute ] [] +Save-MarkdownHelp [-Module ] [-OutputPath ] [-Wiki] [-Command ] [-ReplaceCommandName ] [-ReplaceCommandNameWith ] [-ScriptPath ] [-ReplaceScriptName ] [-ReplaceScriptNameWith ] [-ReplaceLink ] [-ReplaceLinkWith ] [-PassThru] [-SectionOrder ] [-IncludeTopic ] [-ExcludeTopic ] [-ExcludeFile ] [-IncludeFile ] [-IncludeExtension ] [-ExcludeExtension ] [-IncludeSubmodule] [-ExcludeSubModule] [-NoValidValueEnumeration] [-IncludeYamlHeader] [-YamlHeaderInformationType ] [-SkipCommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Script | Configuration | All}] [-FormatAttribute ] [-JsonDataPath ] [-NoJson] [] ``` diff --git a/docs/_data/Help/ConvertTo-MAML.json b/docs/_data/Help/ConvertTo-MAML.json new file mode 100644 index 00000000..ac73d134 --- /dev/null +++ b/docs/_data/Help/ConvertTo-MAML.json @@ -0,0 +1,58 @@ +{ + "Synopsis": "Gets MAML help", + "Description": "Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml.", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + "[Management.Automation.CommandInfo]\nAccepts a command" + ], + "Outputs": [ + "[String]\nThe MAML, as a String. This is the default.", + "[Xml]\nThe MAML, as an XmlDocument (when -XML is passed in)" + ], + "Links": [ + null, + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML" + }, + { + "Title": "EXAMPLE 2", + "Markdown": "", + "Code": "Get-Command Get-MAML | Get-MAML" + }, + { + "Title": "EXAMPLE 3", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML -Compact" + }, + { + "Title": "EXAMPLE 4", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML -XML" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Get-MAML.json b/docs/_data/Help/Get-MAML.json new file mode 100644 index 00000000..ac73d134 --- /dev/null +++ b/docs/_data/Help/Get-MAML.json @@ -0,0 +1,58 @@ +{ + "Synopsis": "Gets MAML help", + "Description": "Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml.", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + "[Management.Automation.CommandInfo]\nAccepts a command" + ], + "Outputs": [ + "[String]\nThe MAML, as a String. This is the default.", + "[Xml]\nThe MAML, as an XmlDocument (when -XML is passed in)" + ], + "Links": [ + null, + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML" + }, + { + "Title": "EXAMPLE 2", + "Markdown": "", + "Code": "Get-Command Get-MAML | Get-MAML" + }, + { + "Title": "EXAMPLE 3", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML -Compact" + }, + { + "Title": "EXAMPLE 4", + "Markdown": "", + "Code": "Get-MAML -Name Get-MAML -XML" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Get-MarkdownHelp.json b/docs/_data/Help/Get-MarkdownHelp.json new file mode 100644 index 00000000..eee1fcd5 --- /dev/null +++ b/docs/_data/Help/Get-MarkdownHelp.json @@ -0,0 +1,42 @@ +{ + "Synopsis": "Gets Markdown Help", + "Description": "Gets Help for a given command, in Markdown", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + "[string]\n\nThe documentation for a single command, in Markdown." + ], + "Links": [ + null, + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "#### Getting Markdown Help ", + "Code": "Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Get-ScriptReference.json b/docs/_data/Help/Get-ScriptReference.json new file mode 100644 index 00000000..46584ca3 --- /dev/null +++ b/docs/_data/Help/Get-ScriptReference.json @@ -0,0 +1,39 @@ +{ + "Synopsis": "Gets a script's references", + "Description": "Gets the external references of a given PowerShell command. These are the commands the script calls, and the types the script uses.", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + null + ], + "Links": [], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Get-Command Get-ScriptReference | Get-ScriptReference" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Get-ScriptStory.json b/docs/_data/Help/Get-ScriptStory.json new file mode 100644 index 00000000..2908c1b2 --- /dev/null +++ b/docs/_data/Help/Get-ScriptStory.json @@ -0,0 +1,39 @@ +{ + "Synopsis": "Gets a Script's story", + "Description": "Gets the Script's \"Story\"\n\nScript Stories are a simple markdown summary of all single-line comments within a script (aside from those in the param block).", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + null + ], + "Links": [], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Get-Command Get-ScriptStory | Get-ScriptStory" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Install-MAML.json b/docs/_data/Help/Install-MAML.json new file mode 100644 index 00000000..d1bb0752 --- /dev/null +++ b/docs/_data/Help/Install-MAML.json @@ -0,0 +1,43 @@ +{ + "Synopsis": "Installs MAML into a module", + "Description": "Installs MAML into a module. \n\nThis generates a single script that: \n* Includes all commands\n* Removes their multiline comments\n* Directs the commands to use external help\n\nYou should then include this script in your module import.\n\nIdeally, you should use the allcommands script", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + "System.Nullable", + "System.IO.FileInfo" + ], + "Links": [ + null, + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Install-MAML -Module HelpOut" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Measure-Help.json b/docs/_data/Help/Measure-Help.json new file mode 100644 index 00000000..ffdf9510 --- /dev/null +++ b/docs/_data/Help/Measure-Help.json @@ -0,0 +1,51 @@ +{ + "Synopsis": "Determines the percentage of documentation", + "Description": "Determines the percentage of documentation in a given script", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + null + ], + "Links": [ + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "dir -Filter *.ps1 | Measure-Help" + }, + { + "Title": "EXAMPLE 2", + "Markdown": "", + "Code": "Get-Command -Module HelpOut | Measure-Help" + }, + { + "Title": "EXAMPLE 3", + "Markdown": "", + "Code": "Measure-Help {\n # This script has some documentation, and then a bunch of code that literally does nothing\n $null = $null # The null equivilancy \n $null * 500 # x times nothing is still nothing\n $null / 100 # Nothing out of 100 \n} | Select-Object -ExpandProperty PercentageDocumented" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Save-MAML.json b/docs/_data/Help/Save-MAML.json new file mode 100644 index 00000000..05485a8c --- /dev/null +++ b/docs/_data/Help/Save-MAML.json @@ -0,0 +1,52 @@ +{ + "Synopsis": "Saves a Module's MAML", + "Description": "Generates a Module's MAML file, and then saves it to the appropriate location.", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + "System.Nullable", + "System.IO.FileInfo" + ], + "Links": [ + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Save-Maml -Module HelpOut" + }, + { + "Title": "EXAMPLE 2", + "Markdown": "", + "Code": "Save-Maml -Module HelpOut -WhatIf" + }, + { + "Title": "EXAMPLE 3", + "Markdown": "", + "Code": "Save-Maml -Module HelpOut -PassThru" + } + ] +} \ No newline at end of file diff --git a/docs/_data/Help/Save-MarkdownHelp.json b/docs/_data/Help/Save-MarkdownHelp.json new file mode 100644 index 00000000..2bfdf4f2 --- /dev/null +++ b/docs/_data/Help/Save-MarkdownHelp.json @@ -0,0 +1,46 @@ +{ + "Synopsis": "Saves a Module's Markdown Help", + "Description": "Get markdown help for each command in a module and saves it to the appropriate location.", + "Parameters": [ + { + "Name": null, + "Type": null, + "Description": "", + "Required": false, + "Position": 0, + "Aliases": null, + "DefaultValue": null, + "Globbing": false, + "PipelineInput": null, + "variableLength": false + } + ], + "Notes": [ + null + ], + "CommandType": "Function", + "Component": [ + null + ], + "Inputs": [ + null + ], + "Outputs": [ + null + ], + "Links": [ + null + ], + "Examples": [ + { + "Title": "EXAMPLE 1", + "Markdown": "", + "Code": "Save-MarkdownHelp -Module HelpOut # Save Markdown to HelpOut/docs" + }, + { + "Title": "EXAMPLE 2", + "Markdown": "", + "Code": "Save-MarkdownHelp -Module HelpOut -Wiki # Save Markdown to ../HelpOut.wiki" + } + ] +} \ No newline at end of file