diff --git a/CHANGELOG.md b/CHANGELOG.md index 83ee2527..8dfd3ed9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +### HelpOut 0.5.1: + +* Save-MarkdownHelp - -OutputPath now handles relative paths (#159) +* Markdown Help Formatting - Trimming Whitespace (#161) (rendering should be unchanged) + +Thanks @PrzemyslawKlys ! + +--- + ### HelpOut 0.5: * Install-MAML - Adding -NoComment (#157) diff --git a/Formatting/PowerShell.Markdown.Help.format.ps1 b/Formatting/PowerShell.Markdown.Help.format.ps1 index 146cb46c..056612b0 100644 --- a/Formatting/PowerShell.Markdown.Help.format.ps1 +++ b/Formatting/PowerShell.Markdown.Help.format.ps1 @@ -208,7 +208,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co } $descriptionLines = @($parameter.description | Out-String -Width 1mb) -split '(?>\r\n|\n)' - $descriptionLines -replace '^-\s', '* ' -join [Environment]::NewLine + $descriptionLines -replace '^-\s', '* ' -ne '' -join [Environment]::NewLine if (-not $helpObject.NoValidValueEnumeration -and $helpCmd -and $helpCmd.Parameters.($parameter.Name)) { $parameterMetadata = $helpCmd.Parameters[$parameter.Name] @@ -244,7 +244,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co Format-Markdown -MarkdownTable -InputObject ([PSCustomObject]$parameterTableInfo) - [Environment]::NewLine * 2 + [Environment]::NewLine } } } @@ -434,14 +434,18 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co & $MarkdownSections.$sectionName } else { $null } if ($sectionContent) { - [Environment]::NewLine + if ($sectionContent -notmatch '^[\r\n]') { + [Environment]::NewLine + } $sectionContent - [Environment]::NewLine + if ($sectionContent -notmatch '[\r\n]$') { + [Environment]::NewLine + } if ($sectionCounter -lt $orderOfSections.Length -and $sectionContent -notmatch '---\s{0,}$') { '---' } } } - ) -join [Environment]::NewLine).Trim() + ) -join [Environment]::NewLine -replace "(?>\r\n|\n){3,}", ([Environment]::NewLine * 2)).Trim() } diff --git a/HelpOut-Help.xml b/HelpOut-Help.xml index 4e7ecfc3..81f63235 100644 --- a/HelpOut-Help.xml +++ b/HelpOut-Help.xml @@ -8,7 +8,7 @@ Gets MAML help - 0.5 + 0.5.1 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.5 + 0.5.1 Gets Help for a given command, in Markdown @@ -703,7 +703,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Gets a script's references - 0.5 + 0.5.1 Gets the external references of a given PowerShell command. These are the commands the script calls, and the types the script uses. @@ -829,7 +829,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Gets a Script's story - 0.5 + 0.5.1 Gets the Script's "Story" @@ -992,7 +992,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help Installs MAML into a module - 0.5 + 0.5.1 Installs MAML into a module. @@ -1428,7 +1428,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Determines the percentage of documentation - 0.5 + 0.5.1 Determines the percentage of documentation in a given script @@ -1571,7 +1571,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Saves a Module's MAML - 0.5 + 0.5.1 Generates a Module's MAML file, and then saves it to the appropriate location. @@ -1832,7 +1832,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes Saves a Module's Markdown Help - 0.5 + 0.5.1 Get markdown help for each command in a module and saves it to the appropriate location. diff --git a/HelpOut.format.ps1xml b/HelpOut.format.ps1xml index 58fb544c..f1894db2 100644 --- a/HelpOut.format.ps1xml +++ b/HelpOut.format.ps1xml @@ -1,5 +1,5 @@ - + @@ -321,7 +321,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co } $descriptionLines = @($parameter.description | Out-String -Width 1mb) -split '(?>\r\n|\n)' - $descriptionLines -replace '^-\s', '* ' -join [Environment]::NewLine + $descriptionLines -replace '^-\s', '* ' -ne '' -join [Environment]::NewLine if (-not $helpObject.NoValidValueEnumeration -and $helpCmd -and $helpCmd.Parameters.($parameter.Name)) { $parameterMetadata = $helpCmd.Parameters[$parameter.Name] @@ -357,7 +357,7 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co & ${HelpOut_Format-Markdown} -MarkdownTable -InputObject ([PSCustomObject]$parameterTableInfo) - [Environment]::NewLine * 2 + [Environment]::NewLine } } } @@ -547,16 +547,20 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co & $MarkdownSections.$sectionName } else { $null } if ($sectionContent) { - [Environment]::NewLine + if ($sectionContent -notmatch '^[\r\n]') { + [Environment]::NewLine + } $sectionContent - [Environment]::NewLine + if ($sectionContent -notmatch '[\r\n]$') { + [Environment]::NewLine + } if ($sectionCounter -lt $orderOfSections.Length -and $sectionContent -notmatch '---\s{0,}$') { '---' } } } - ) -join [Environment]::NewLine).Trim() + ) -join [Environment]::NewLine -replace "(?>\r\n|\n){3,}", ([Environment]::NewLine * 2)).Trim() diff --git a/HelpOut.psd1 b/HelpOut.psd1 index 04a618c8..f4bce011 100644 --- a/HelpOut.psd1 +++ b/HelpOut.psd1 @@ -7,7 +7,7 @@ ModuleToProcess='HelpOut.psm1' FormatsToProcess='HelpOut.format.ps1xml' TypesToProcess='HelpOut.types.ps1xml' - ModuleVersion='0.5' + ModuleVersion='0.5.1' PrivateData = @{ PSData = @{ ProjectURI = 'https://github.com/StartAutomating/HelpOut' @@ -15,12 +15,12 @@ Tags = 'Markdown', 'Help','PowerShell' ReleaseNotes = @' -### HelpOut 0.5: +### HelpOut 0.5.1: -* Install-MAML - Adding -NoComment (#157) -* Install-MAML - Adding -Minify (#158) +* Save-MarkdownHelp - -OutputPath now handles relative paths (#159) +* Markdown Help Formatting - Trimming Whitespace (#161) (rendering should be unchanged) -Thanks @potatoqualitee ! +Thanks @PrzemyslawKlys ! --- diff --git a/HelpOut.types.ps1xml b/HelpOut.types.ps1xml index 3e2f63e6..c48460f2 100644 --- a/HelpOut.types.ps1xml +++ b/HelpOut.types.ps1xml @@ -1,5 +1,5 @@ - + PowerShell.Markdown.Help diff --git a/Save-MarkdownHelp.ps1 b/Save-MarkdownHelp.ps1 index 4bbd055a..372d3de4 100644 --- a/Save-MarkdownHelp.ps1 +++ b/Save-MarkdownHelp.ps1 @@ -203,6 +203,9 @@ } else { Join-Path $theModuleRoot "docs" # Otherwise, it's the docs subdirectory. } + } else { + # If -OutputPath was provided, we want to make sure it becomes an absolute path + $OutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath) } # If the -OutputPath does not exist diff --git a/allcommands.ps1 b/allcommands.ps1 index 46b9b91f..deb7b129 100644 --- a/allcommands.ps1 +++ b/allcommands.ps1 @@ -1573,6 +1573,9 @@ function Save-MarkdownHelp } else { Join-Path $theModuleRoot "docs" # Otherwise, it's the docs subdirectory. } + } else { + # If -OutputPath was provided, we want to make sure it becomes an absolute path + $OutputPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($OutputPath) } # If the -OutputPath does not exist diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md index 2168da76..93b2f422 100644 --- a/docs/CHANGELOG.md +++ b/docs/CHANGELOG.md @@ -1,3 +1,12 @@ +### HelpOut 0.5.1: + +* Save-MarkdownHelp - -OutputPath now handles relative paths (#159) +* Markdown Help Formatting - Trimming Whitespace (#161) (rendering should be unchanged) + +Thanks @PrzemyslawKlys ! + +--- + ### HelpOut 0.5: * Install-MAML - Adding -NoComment (#157) diff --git a/docs/ConvertTo-MAML.md b/docs/ConvertTo-MAML.md index 198b0433..364d9c88 100644 --- a/docs/ConvertTo-MAML.md +++ b/docs/ConvertTo-MAML.md @@ -1,40 +1,24 @@ Get-MAML -------- - - - ### Synopsis Gets MAML help - - --- - ### Description Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml. - - --- - ### Related Links * [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) - - * [Save-MAML](Save-MAML.md) - - - - --- - ### Examples > EXAMPLE 1 @@ -57,132 +41,69 @@ Get-MAML -Name Get-MAML -Compact Get-MAML -Name Get-MAML -XML ``` - --- - ### Parameters #### **Name** - The name of or more commands. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |1 |true (ByPropertyName)| - - #### **Module** - The name of one or more modules. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **CommandInfo** - The CommandInfo object (returned from Get-Command). - - - - - |Type |Required|Position|PipelineInput | |-----------------|--------|--------|--------------| |`[CommandInfo[]]`|true |named |true (ByValue)| - - #### **Compact** - If set, the generated MAML will be compact (no extra whitespace or indentation). If not set, the MAML will be indented. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **XML** - If set, will return the MAML as an XmlDocument. The default is to return the MAML as a string. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **NoVersion** - If set, the generate MAML will not contain a version number. This slightly reduces the size of the MAML file, and reduces the rate of changes in the MAML file. - - - - - |Type |Required|Position|PipelineInput|Aliases | |----------|--------|--------|-------------|-----------| |`[Switch]`|false |named |false |Unversioned| - - - - --- - ### Inputs [Management.Automation.CommandInfo] Accepts a command - - --- - ### Outputs * [String] The MAML, as a String. This is the default. - * [Xml] The MAML, as an XmlDocument (when -XML is passed in) - - - - - --- - ### Syntax ```PowerShell Get-MAML [-Compact] [-XML] [-NoVersion] [] diff --git a/docs/Get-MAML.md b/docs/Get-MAML.md index 198b0433..364d9c88 100644 --- a/docs/Get-MAML.md +++ b/docs/Get-MAML.md @@ -1,40 +1,24 @@ Get-MAML -------- - - - ### Synopsis Gets MAML help - - --- - ### Description Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml. - - --- - ### Related Links * [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) - - * [Save-MAML](Save-MAML.md) - - - - --- - ### Examples > EXAMPLE 1 @@ -57,132 +41,69 @@ Get-MAML -Name Get-MAML -Compact Get-MAML -Name Get-MAML -XML ``` - --- - ### Parameters #### **Name** - The name of or more commands. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |1 |true (ByPropertyName)| - - #### **Module** - The name of one or more modules. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **CommandInfo** - The CommandInfo object (returned from Get-Command). - - - - - |Type |Required|Position|PipelineInput | |-----------------|--------|--------|--------------| |`[CommandInfo[]]`|true |named |true (ByValue)| - - #### **Compact** - If set, the generated MAML will be compact (no extra whitespace or indentation). If not set, the MAML will be indented. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **XML** - If set, will return the MAML as an XmlDocument. The default is to return the MAML as a string. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **NoVersion** - If set, the generate MAML will not contain a version number. This slightly reduces the size of the MAML file, and reduces the rate of changes in the MAML file. - - - - - |Type |Required|Position|PipelineInput|Aliases | |----------|--------|--------|-------------|-----------| |`[Switch]`|false |named |false |Unversioned| - - - - --- - ### Inputs [Management.Automation.CommandInfo] Accepts a command - - --- - ### Outputs * [String] The MAML, as a String. This is the default. - * [Xml] The MAML, as an XmlDocument (when -XML is passed in) - - - - - --- - ### Syntax ```PowerShell Get-MAML [-Compact] [-XML] [-NoVersion] [] diff --git a/docs/Get-MarkdownHelp.md b/docs/Get-MarkdownHelp.md index 34dd9b37..ddb6d58e 100644 --- a/docs/Get-MarkdownHelp.md +++ b/docs/Get-MarkdownHelp.md @@ -1,40 +1,24 @@ Get-MarkdownHelp ---------------- - - - ### Synopsis Gets Markdown Help - - --- - ### Description Gets Help for a given command, in Markdown - - --- - ### Related Links * [Save-MarkdownHelp](Save-MarkdownHelp.md) - - * [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) - - - - --- - ### Examples #### Getting Markdown Help @@ -42,142 +26,72 @@ Gets Help for a given command, in Markdown Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help ``` - --- - ### Parameters #### **Name** - The name of the specified command or concept. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |1 |true (ByPropertyName)| - - #### **Wiki** - If set, will generate a markdown wiki. Links will be relative to the current path, and will not include the .md extensions - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **GitHubDocRoot** - If set, will interlink documentation as if it were for GitHub pages, beneath a given directory - - - - - |Type |Required|Position|PipelineInput|Aliases | |----------|--------|--------|-------------|--------------| |`[String]`|false |named |false |GitHubPageRoot| - - #### **Rename** - If provided, will rename the help topic before getting markdown. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |named |true (ByPropertyName)| - - #### **SectionOrder** - The order of the sections. If not provided, this will be the order they are defined in the formatter. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **NoValidValueEnumeration** - If set, will not enumerate valid values and enums of parameters. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **IncludeYamlHeader** - If set, will not attach a YAML header to the generated help. - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|---------------------|------------------------------------| |`[Switch]`|false |named |true (ByPropertyName)|IncludeFrontMatter
IncludeHeader| - - #### **YamlHeaderInformationType** - The type of information to include in the YAML Header - - - Valid Values: * Command * Help * Metadata - - - - - |Type |Required|Position|PipelineInput|Aliases | |------------|--------|--------|-------------|------------------| |`[String[]]`|false |named |false |YamlHeaderInfoType| - - #### **FormatAttribute** - The formatting used for unknown attributes. Any key or property in this object will be treated as a potential typename Any value will be the desired formatting. @@ -185,51 +99,29 @@ If the value is a [ScriptBlock], the [ScriptBlock] will be run. If the value is a [string], it will be expanded In either context, `$_` will be the current attribute. - - - - - |Type |Required|Position|PipelineInput| |------------|--------|--------|-------------| |`[PSObject]`|false |named |false | - - - - --- - ### Outputs * [string] The documentation for a single command, in Markdown. - - - - - --- - How It Works ------------ ### For each Command We start off by copying the bound parameters and then we call Get-Help. - - If we could not Get-Help, we error out. We need to decorate the output of Get-Help so it renders as markdown, so we pipe thru all results from Get-Help. Get-Help can return either a help topic or command help. Help topics will be returned as a string (which we will output as-is for now). - - - - Command Help will be returned as an object We decorate that object with the typename `PowerShell.Markdown.Help`. $helpObj.pstypenames.clear() Then we attach parameters passed to this command to the help object. * `-Rename` will become `[string] .Rename` * `-SectionOrder` will become `[string[]] .SectionOrder` @@ -241,10 +133,8 @@ How It Works After we've attached all of the properties, we simply output the object. PowerShell.Markdown.Help formatter will display it exactly as we'd like it. - --- - ### Syntax ```PowerShell Get-MarkdownHelp [[-Name] ] [-Wiki] [-GitHubDocRoot ] [-Rename ] [-SectionOrder ] [-NoValidValueEnumeration] [-IncludeYamlHeader] [-YamlHeaderInformationType ] [-FormatAttribute ] [] diff --git a/docs/Get-ScriptReference.md b/docs/Get-ScriptReference.md index 8179dc76..b7ec2da4 100644 --- a/docs/Get-ScriptReference.md +++ b/docs/Get-ScriptReference.md @@ -1,26 +1,17 @@ Get-ScriptReference ------------------- - - - ### 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. - - --- - ### Examples > EXAMPLE 1 @@ -28,61 +19,32 @@ Gets the external references of a given PowerShell command. These are the comma Get-Command Get-ScriptReference | Get-ScriptReference ``` - --- - ### Parameters #### **FilePath** - The path to a file - - - - - |Type |Required|Position|PipelineInput |Aliases | |------------|--------|--------|---------------------|--------| |`[String[]]`|true |1 |true (ByPropertyName)|Fullname| - - #### **ScriptBlock** - One or more PowerShell ScriptBlocks - - - - - |Type |Required|Position|PipelineInput |Aliases | |-----------------|--------|--------|------------------------------|----------| |`[ScriptBlock[]]`|true |1 |true (ByValue, ByPropertyName)|Definition| - - #### **Recurse** - If set, will recursively find references. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - - - --- - ### Syntax ```PowerShell Get-ScriptReference [-FilePath] [-Recurse] [] diff --git a/docs/Get-ScriptStory.md b/docs/Get-ScriptStory.md index 8d2d4a96..bdb317f9 100644 --- a/docs/Get-ScriptStory.md +++ b/docs/Get-ScriptStory.md @@ -1,28 +1,19 @@ Get-ScriptStory --------------- - - - ### Synopsis Gets a Script's story - - --- - ### Description Gets the Script's "Story" Script Stories are a simple markdown summary of all single-line comments within a script (aside from those in the param block). - - --- - ### Examples > EXAMPLE 1 @@ -30,72 +21,38 @@ Script Stories are a simple markdown summary of all single-line comments within Get-Command Get-ScriptStory | Get-ScriptStory ``` - --- - ### Parameters #### **ScriptBlock** - A script block - - - - - |Type |Required|Position|PipelineInput | |---------------|--------|--------|--------------| |`[ScriptBlock]`|true |1 |true (ByValue)| - - #### **Text** - A block of text - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|------------------------------|-----------------------------| |`[String]`|true |1 |true (ByValue, ByPropertyName)|ScriptContents
Definition| - - #### **RegionName** - The friendly names of code regions or begin,process, or end blocks. - - - - - |Type |Required|Position|PipelineInput| |---------------|--------|--------|-------------| |`[IDictionary]`|false |named |false | - - #### **HeadingSize** - - - |Type |Required|Position|PipelineInput| |---------|--------|--------|-------------| |`[Int32]`|false |named |false | - - - - --- - ### Syntax ```PowerShell Get-ScriptStory [-ScriptBlock] [-RegionName ] [-HeadingSize ] [] diff --git a/docs/Install-MAML.md b/docs/Install-MAML.md index afc97c88..087dc5bc 100644 --- a/docs/Install-MAML.md +++ b/docs/Install-MAML.md @@ -1,17 +1,11 @@ Install-MAML ------------ - - - ### Synopsis Installs MAML into a module - - --- - ### Description Installs MAML into a module. @@ -25,25 +19,15 @@ You should then include this script in your module import. Ideally, you should use the allcommands script - - --- - ### Related Links * [Save-MAML](Save-MAML.md) - - * [ConvertTo-MAML](ConvertTo-MAML.md) - - - - --- - ### Examples > EXAMPLE 1 @@ -51,243 +35,119 @@ Ideally, you should use the allcommands script Install-MAML -Module HelpOut ``` - --- - ### Parameters #### **Module** - The name of one or more modules. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|true |1 |true (ByPropertyName)| - - #### **NoRefresh** - If set, will refresh the documentation for the module before generating the commands file. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **Compact** - If set, will compact the generated MAML. This will be ignored if -Refresh is not passed, since no new MAML will be generated. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **ScriptName** - The name of the combined script. By default, allcommands.ps1. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |2 |true (ByPropertyName)| - - #### **FunctionRoot** - The root directories containing functions. If not provided, the function root will be the module root. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **NoRecurse** - If set, the function roots will not be recursively searched. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **Encoding** - The encoding of the combined script. By default, UTF8. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[Encoding]`|false |3 |true (ByPropertyName)| - - #### **Exclude** - A list of wildcards to exclude. This list will always contain the ScriptName. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **NoVersion** - If set, the generated MAML will not contain a version number. This slightly reduces the size of the MAML file, and reduces the rate of changes in the MAML file. - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|---------------------|-----------| |`[Switch]`|false |named |true (ByPropertyName)|Unversioned| - - #### **Culture** - If provided, will save the MAML to a different directory than the current UI culture. - - - - - |Type |Required|Position|PipelineInput | |---------------|--------|--------|---------------------| |`[CultureInfo]`|false |named |true (ByPropertyName)| - - #### **NoComment** - If set, will remove comments within functions when generating allcommands.ps1 - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|---------------------|-------------------------------------------------| |`[Switch]`|false |named |true (ByPropertyName)|NoBlockComments
NoBlockComment
NoComments| - - #### **PassThru** - If set, will return the files that were generated. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **Minify** - If set, will minify the code in allcommands.ps1. By default, this will stream down the latest version of [PSMinifier](https://github.com/StartAutomating/PSMinifier). - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **MinifierSource** - If -MinifierSource is like `*Gallery*`, it will use the PowerShell Gallery to download. If -MinifierSource is an alternate URL, it will download the contents of that URL (it must define a function named Compress-ScriptBlock). - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |named |true (ByPropertyName)| - - - - --- - ### Outputs * [Nullable](https://learn.microsoft.com/en-us/dotnet/api/System.Nullable) - * [IO.FileInfo](https://learn.microsoft.com/en-us/dotnet/api/System.IO.FileInfo) - - - - - --- - ### Syntax ```PowerShell Install-MAML [-Module] [-NoRefresh] [-Compact] [[-ScriptName] ] [-FunctionRoot ] [-NoRecurse] [[-Encoding] ] [-Exclude ] [-NoVersion] [-Culture ] [-NoComment] [-PassThru] [-Minify] [-MinifierSource ] [] diff --git a/docs/Measure-Help.md b/docs/Measure-Help.md index 9db9a8d4..6e623717 100644 --- a/docs/Measure-Help.md +++ b/docs/Measure-Help.md @@ -1,36 +1,22 @@ Measure-Help ------------ - - - ### Synopsis Determines the percentage of documentation - - --- - ### Description Determines the percentage of documentation in a given script - - --- - ### Related Links * [Get-Help](https://learn.microsoft.com/powershell/module/Microsoft.PowerShell.Core/Get-Help) - - - - --- - ### Examples > EXAMPLE 1 @@ -53,61 +39,32 @@ Measure-Help { } | Select-Object -ExpandProperty PercentageDocumented ``` - --- - ### Parameters #### **FilePath** - The path to the file - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|---------------------|--------| |`[String]`|true |1 |true (ByPropertyName)|Fullname| - - #### **ScriptBlock** - A PowerShell script block - - - - - |Type |Required|Position|PipelineInput | |---------------|--------|--------|---------------------| |`[ScriptBlock]`|true |named |true (ByPropertyName)| - - #### **Name** - The name of the script being measured. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |named |true (ByPropertyName)| - - - - --- - ### Syntax ```PowerShell Measure-Help [-FilePath] [] diff --git a/docs/PowerShell/Markdown/Help/HideSection.md b/docs/PowerShell/Markdown/Help/HideSection.md index 67d6ea56..f7c7641c 100644 --- a/docs/PowerShell/Markdown/Help/HideSection.md +++ b/docs/PowerShell/Markdown/Help/HideSection.md @@ -1,33 +1,20 @@ 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 @@ -42,17 +29,8 @@ Valid Values: * 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 index b32af26f..a7356940 100644 --- a/docs/PowerShell/Markdown/Help/Save.md +++ b/docs/PowerShell/Markdown/Help/Save.md @@ -1,36 +1,22 @@ 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 @@ -38,51 +24,28 @@ Saves a Markdown Help Topic to a file. (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 index 95d0f069..65cec560 100644 --- a/docs/PowerShell/Markdown/Help/ShowSection.md +++ b/docs/PowerShell/Markdown/Help/ShowSection.md @@ -1,33 +1,20 @@ 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 @@ -42,17 +29,8 @@ Valid Values: * 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 index 68796171..6e64b092 100644 --- a/docs/PowerShell/Markdown/Help/ToMarkdown.md +++ b/docs/PowerShell/Markdown/Help/ToMarkdown.md @@ -1,26 +1,17 @@ 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 @@ -28,27 +19,15 @@ Returns the content of this help topic as a markdown string. (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 | - - - - --- diff --git a/docs/Save-MAML.md b/docs/Save-MAML.md index 7800e04d..cf709913 100644 --- a/docs/Save-MAML.md +++ b/docs/Save-MAML.md @@ -1,36 +1,22 @@ Save-MAML --------- - - - ### Synopsis Saves a Module's MAML - - --- - ### Description Generates a Module's MAML file, and then saves it to the appropriate location. - - --- - ### Related Links * [Get-MAML](Get-MAML.md) - - - - --- - ### Examples > EXAMPLE 1 @@ -48,87 +34,45 @@ Save-Maml -Module HelpOut -WhatIf Save-Maml -Module HelpOut -PassThru ``` - --- - ### Parameters #### **Module** - The name of one or more modules. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **Compact** - If set, the generated MAML will be compact (no extra whitespace or indentation). If not set, the MAML will be indented. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **Culture** - If provided, will save the MAML to a different directory than the current UI culture. - - - - - |Type |Required|Position|PipelineInput | |---------------|--------|--------|---------------------| |`[CultureInfo]`|false |named |true (ByPropertyName)| - - #### **NoVersion** - If set, the generated MAML will not contain a version number. This slightly reduces the size of the MAML file, and reduces the rate of changes in the MAML file. - - - - - |Type |Required|Position|PipelineInput|Aliases | |----------|--------|--------|-------------|-----------| |`[Switch]`|false |named |false |Unversioned| - - #### **PassThru** - If set, will return the files that were generated. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **WhatIf** -WhatIf is an automatic variable that is created when a command has ```[CmdletBinding(SupportsShouldProcess)]```. -WhatIf is used to see what would happen, or return operations without executing them @@ -138,28 +82,17 @@ If set, will return the files that were generated. If you pass ```-Confirm:$false``` you will not be prompted. - If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$confirmImpactPreference```, you will not be prompted unless -Confirm is passed. - - --- - ### Outputs * [Nullable](https://learn.microsoft.com/en-us/dotnet/api/System.Nullable) - * [IO.FileInfo](https://learn.microsoft.com/en-us/dotnet/api/System.IO.FileInfo) - - - - - --- - ### Syntax ```PowerShell Save-MAML [-Compact] [-Culture ] [-NoVersion] [-PassThru] [-WhatIf] [-Confirm] [] diff --git a/docs/Save-MarkdownHelp.md b/docs/Save-MarkdownHelp.md index 66daabf1..a6b8a40f 100644 --- a/docs/Save-MarkdownHelp.md +++ b/docs/Save-MarkdownHelp.md @@ -1,36 +1,22 @@ Save-MarkdownHelp ----------------- - - - ### Synopsis Saves a Module's Markdown Help - - --- - ### Description Get markdown help for each command in a module and saves it to the appropriate location. - - --- - ### Related Links * [Get-MarkdownHelp](Get-MarkdownHelp.md) - - - - --- - ### Examples > EXAMPLE 1 @@ -43,337 +29,168 @@ Save-MarkdownHelp -Module HelpOut # Save Markdown to HelpOut/docs Save-MarkdownHelp -Module HelpOut -Wiki # Save Markdown to ../HelpOut.wiki ``` - --- - ### Parameters #### **Module** - The name of one or more modules. - - - - - |Type |Required|Position|PipelineInput |Aliases| |------------|--------|--------|---------------------|-------| |`[String[]]`|false |named |true (ByPropertyName)|Name | - - #### **OutputPath** - The output path. If not provided, will be assumed to be the "docs" folder of a given module (unless -Wiki is specified) - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[String]`|false |named |true (ByPropertyName)| - - #### **Wiki** - If set, will interlink documentation as if it were a wiki. Implied when -OutputPath contains 'wiki'. If provided without -OutputPath, will assume that a wiki resides in a sibling directory of the module. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **Command** - If provided, will generate documentation for additional commands. - - - - - |Type |Required|Position|PipelineInput | |-----------------|--------|--------|---------------------| |`[CommandInfo[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceCommandName** - Replaces parts of the names of the commands provided in the -Command parameter. -ReplaceScriptName is treated as a regular expression. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceCommandNameWith** - If provided, will replace parts of the names of the scripts discovered in a -Command parameter with a given Regex replacement. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ScriptPath** - If provided, will generate documentation for any scripts found within these paths. -ScriptPath can be either a file name or a full path. If an exact match is not found -ScriptPath will also check to see if there is a wildcard match. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceScriptName** - If provided, will replace parts of the names of the scripts discovered in a -ScriptDirectory beneath a module. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceScriptNameWith** - If provided, will replace parts of the names of the scripts discovered in a -ScriptDirectory beneath a module with a given Regex replacement. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceLink** - If provided, will replace links discovered in markdown content. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ReplaceLinkWith** - If provided, will replace links discovered in markdown content with a given Regex replacement. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **PassThru** - If set, will output changed or created files. - - - - - |Type |Required|Position|PipelineInput| |----------|--------|--------|-------------| |`[Switch]`|false |named |false | - - #### **SectionOrder** - The order of the sections. If not provided, this will be the order they are defined in the formatter. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **IncludeTopic** - One or more topic files to include. Topic files will be treated as markdown and directly copied inline. By default ```\.help\.txt$``` and ```\.md$``` - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ExcludeTopic** - One or more topic file patterns to exclude. Topic files that match this pattern will not be included. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **ExcludeFile** - One or more files to exclude. By default, this is treated as a wildcard. If the file name starts and ends with slashes, it will be treated as a Regular Expression. - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **IncludeExtension** - One or more extensions to include. By default, .css, .gif, .htm, .html, .js, .jpg, .jpeg, .mp4, .png, .svg - - - - - |Type |Required|Position|PipelineInput | |------------|--------|--------|---------------------| |`[String[]]`|false |named |true (ByPropertyName)| - - #### **NoValidValueEnumeration** - If set, will not enumerate valid values and enums of parameters. - - - - - |Type |Required|Position|PipelineInput | |----------|--------|--------|---------------------| |`[Switch]`|false |named |true (ByPropertyName)| - - #### **IncludeYamlHeader** - If set, will not attach a YAML header to the generated help. - - - - - |Type |Required|Position|PipelineInput |Aliases | |----------|--------|--------|---------------------|------------------------------------| |`[Switch]`|false |named |true (ByPropertyName)|IncludeFrontMatter
IncludeHeader| - - #### **YamlHeaderInformationType** - The type of information to include in the YAML Header - - - Valid Values: * Command * Help * Metadata - - - - - |Type |Required|Position|PipelineInput|Aliases | |------------|--------|--------|-------------|------------------| |`[String[]]`|false |named |false |YamlHeaderInfoType| - - #### **SkipCommandType** - A list of command types to skip. If not provided, all types of commands from the module will be saved as a markdown document. - - - Valid Values: * Alias @@ -386,19 +203,11 @@ Valid Values: * Configuration * All - - - - - |Type |Required|Position|PipelineInput |Aliases | |------------------|--------|--------|---------------------|---------------------------------------------------------------| |`[CommandTypes[]]`|false |named |true (ByPropertyName)|SkipCommandTypes
ExcludeCommandType
ExcludeCommandTypes| - - #### **FormatAttribute** - The formatting used for unknown attributes. Any key or property in this object will be treated as a potential typename Any value will be the desired formatting. @@ -406,22 +215,12 @@ If the value is a [ScriptBlock], the [ScriptBlock] will be run. If the value is a [string], it will be expanded In either context, `$_` will be the current attribute. - - - - - |Type |Required|Position|PipelineInput| |------------|--------|--------|-------------| |`[PSObject]`|false |named |false | - - - - --- - ### Syntax ```PowerShell Save-MarkdownHelp [-Module ] [-OutputPath ] [-Wiki] [-Command ] [-ReplaceCommandName ] [-ReplaceCommandNameWith ] [-ScriptPath ] [-ReplaceScriptName ] [-ReplaceScriptNameWith ] [-ReplaceLink ] [-ReplaceLinkWith ] [-PassThru] [-SectionOrder ] [-IncludeTopic ] [-ExcludeTopic ] [-ExcludeFile ] [-IncludeExtension ] [-NoValidValueEnumeration] [-IncludeYamlHeader] [-YamlHeaderInformationType ] [-SkipCommandType {Alias | Function | Filter | Cmdlet | ExternalScript | Application | Script | Configuration | All}] [-FormatAttribute ] []