Skip to content

Commit 33ed6cb

Browse files
StartAutomatingStartAutomating
authored
Merge pull request #153 from StartAutomating/HelpOut-AttributeFormatting
HelpOut 0.4.9
2 parents a75a0da + db70ad4 commit 33ed6cb

13 files changed

Lines changed: 373 additions & 45 deletions

‎CHANGELOG.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,14 @@
1+
### HelpOut 0.4.9:
2+
3+
* Supporting custom attribute formatting with -FormatAttribute (#147)
4+
* Markdown Formatter - Honoring .FormatAttribute (#148)
5+
* Get-MarkdownHelp -FormatAttribute (#149)
6+
* Save-MarkdownHelp -FormatAttribute (#150)
7+
* Extended Type Formatting - Improving handling of empty directories (#146)
8+
* Updating HelpOut PSA (#152)
9+
10+
---
11+
112
### HelpOut 0.4.8:
213

314
* Markdown Help Improvements:

‎Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -79,6 +79,9 @@ foreach ($extendedType in $extendedTypeNames) {
7979

8080
})
8181

82+
# If there were no member files, there's no point in generating a summary.
83+
if (-not $memberFiles) { continue }
84+
8285
$ExtendedTypeDocFile = Join-Path $outputPath "$(
8386
($extendedType -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar
8487
)$([IO.Path]::DirectorySeparatorChar)README.md"

‎Formatting/PowerShell.Markdown.Help.format.ps1‎

Lines changed: 73 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,18 @@
11
Write-FormatView -TypeName PowerShell.Markdown.Help -Action {
2-
$helpObject = $_
2+
$helpObject = $_
33
$helpCmd = $ExecutionContext.SessionState.InvokeCommand.GetCommand($helpObject.Name, 'All')
4+
$resolvedHelpCmd =
5+
if ($helpCmd -is [Management.Automation.AliasInfo]) {
6+
$resolved = helpCmd.ResolvedCommand
7+
while ($resolved.ResolvedCommand) {
8+
$resolved = $resolved.ResolvedCommand
9+
}
10+
$resolved
11+
} else {
12+
$helpCmd
13+
}
14+
15+
416
$helpCmdMetadata = [Management.Automation.CommandMetadata]$helpCmd
517

618
$MarkdownSections = [Ordered]@{
@@ -22,6 +34,43 @@
2234
[Environment]::NewLine + $desc.text + [Environment]::NewLine
2335
}
2436
}
37+
CommandAttribute = {
38+
39+
if (-not $helpObject.FormatAttribute) { return }
40+
41+
$CmdAttributes =
42+
if ($resolvedHelpCmd.ImplementingType) {
43+
$resolvedHelpCmd.ImplementingType.GetCustomAttributes()
44+
} elseif ($resolvedHelpCmd.ScriptBlock) {
45+
$resolvedHelpCmd.ScriptBlock.Attributes
46+
}
47+
48+
if (-not $CmdAttributes) { return }
49+
50+
foreach ($attr in $CmdAttributes) {
51+
$attrType = $attr.GetType()
52+
$attrFormatting =
53+
if ($helpObject.FormatAttribute.$($attrType.FullName)) {
54+
$helpObject.FormatAttribute.$($attrType.FullName)
55+
}
56+
elseif ($helpObject.FormatAttribute.$($attrType.Name)) {
57+
$helpObject.FormatAttribute.$($attrType.Name)
58+
}
59+
elseif ($helpObject.FormatAttribute.$($attrType.Name -replace 'Attribute$')) {
60+
$helpObject.FormatAttribute.$($attrType.Name -replace 'Attribute$')
61+
}
62+
63+
if (-not $attrFormatting) { continue }
64+
65+
$_ = $attr
66+
if ($attrFormatting -is [string]) {
67+
$ExecutionContext.SessionState.InvokeCommand.ExpandString($attrFormatting)
68+
} elseif ($attrFormatting -is [scriptblock]) {
69+
$attrFormatting | Out-Host
70+
& ([ScriptBlock]::Create($attrFormatting))
71+
}
72+
}
73+
}
2574
RelatedLinks = {
2675
if ($helpObject.RelatedLinks) {
2776
Format-Markdown -Heading "Related Links" -headingsize 3
@@ -117,6 +166,29 @@
117166

118167
Format-Markdown -HeadingSize 4 -Heading $parameterDisplayName
119168

169+
if ($resolvedHelpCmd -and
170+
$resolvedHelpCmd.Parameters[$parameter.Name].Attributes) {
171+
172+
$paramAttributes = $resolvedHelpCmd.Parameters[$parameter.Name].Attributes
173+
foreach ($attr in $paramAttributes) {
174+
$attrType = $attr.GetType()
175+
$attrFormatting =
176+
if ($helpObject.FormatAttribute.$($attrType.FullName)) {
177+
$helpObject.FormatAttribute.$($attrType.FullName)
178+
}
179+
elseif ($helpObject.FormatAttribute.($attrType.Name)) {
180+
$helpObject.FormatAttribute.($attrType.Name)
181+
}
182+
if (-not $attrFormatting) { continue }
183+
$_ = $attr
184+
if ($attrFormatting -is [string]) {
185+
$ExecutionContext.SessionState.InvokeCommand.ExpandString($attrFormatting)
186+
} elseif ($attrFormatting -is [scriptblock]) {
187+
. ([ScriptBlock]::Create($attrFormatting))
188+
}
189+
}
190+
}
191+
120192
if ($parameter.Name -in 'WhatIf', 'Confirm') {
121193
"-$($parameter.Name) " +
122194
'is an automatic variable that is created when a command has ```[CmdletBinding(SupportsShouldProcess)]```.'

‎Get-MarkdownHelp.ps1‎

Lines changed: 17 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,8 @@
55
.DESCRIPTION
66
Gets Help for a given command, in Markdown
77
.EXAMPLE
8-
Get-MarkdownHelp Get-Help
8+
##### Getting Markdown Help
9+
Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help
910
.LINK
1011
Save-MarkdownHelp
1112
.LINK
@@ -60,7 +61,16 @@
6061
[ValidateSet('Command','Help','Metadata')]
6162
[Alias('YamlHeaderInfoType')]
6263
[string[]]
63-
$YamlHeaderInformationType
64+
$YamlHeaderInformationType,
65+
66+
# The formatting used for unknown attributes.
67+
# Any key or property in this object will be treated as a potential typename
68+
# Any value will be the desired formatting.
69+
# If the value is a [ScriptBlock], the [ScriptBlock] will be run.
70+
# If the value is a [string], it will be expanded
71+
# In either context, `$_` will be the current attribute.
72+
[PSObject]
73+
$FormatAttribute
6474
)
6575

6676
process
@@ -95,8 +105,8 @@
95105
$helpObj = $_
96106
# Command Help will be returned as an object
97107
# We decorate that object with the typename `PowerShell.Markdown.Help`.
98-
$helpObj.pstypenames.clear()
99-
$helpObj.pstypenames.add('PowerShell.Markdown.Help')
108+
# $helpObj.pstypenames.clear()
109+
$helpObj.pstypenames.insert(0,'PowerShell.Markdown.Help')
100110
$IsHelpAboutAlias = $helpObj.Name -ne $gotHelp.Name
101111
$helpObj | Add-Member NoteProperty IsAlias $IsHelpAboutAlias -Force
102112
if ($IsHelpAboutAlias) {
@@ -129,6 +139,9 @@
129139
# * `-NoValidValueEnumeration`
130140
$helpObj | Add-Member NoteProperty YamlHeaderInformationType $YamlHeaderInformationType -Force
131141

142+
if ($FormatAttribute) {
143+
$helpObj | Add-Member NoteProperty FormatAttribute $FormatAttribute -Force
144+
}
132145

133146
# After we've attached all of the properties, we simply output the object.
134147
# PowerShell.Markdown.Help formatter will display it exactly as we'd like it.

‎HelpOut-Help.xml‎

Lines changed: 82 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
<maml:description>
99
<maml:para>Gets MAML help</maml:para>
1010
</maml:description>
11-
<dev:version>0.4.8</dev:version>
11+
<dev:version>0.4.9</dev:version>
1212
</command:details>
1313
<maml:description>
1414
<maml:para>Gets help for a given command, as MAML (Microsoft Assistance Markup Language) xml.</maml:para>
@@ -400,7 +400,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
400400
<maml:description>
401401
<maml:para>Gets Markdown Help</maml:para>
402402
</maml:description>
403-
<dev:version>0.4.8</dev:version>
403+
<dev:version>0.4.9</dev:version>
404404
</command:details>
405405
<maml:description>
406406
<maml:para>Gets Help for a given command, in Markdown</maml:para>
@@ -513,9 +513,45 @@ If not provided, this will be the order they are defined in the formatter.</maml
513513
<dev:defaultValue>
514514
</dev:defaultValue>
515515
</command:parameter>
516+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
517+
<maml:name>FormatAttribute</maml:name>
518+
<maml:description>
519+
<maml:para>The formatting used for unknown attributes.
520+
Any key or property in this object will be treated as a potential typename
521+
Any value will be the desired formatting.
522+
If the value is a [ScriptBlock], the [ScriptBlock] will be run.
523+
If the value is a [string], it will be expanded
524+
In either context, `$_` will be the current attribute.</maml:para>
525+
</maml:description>
526+
<command:parameterValue required="false" variableLength="true">Psobject</command:parameterValue>
527+
<dev:type>
528+
<maml:name>Psobject</maml:name>
529+
<maml:uri />
530+
</dev:type>
531+
<dev:defaultValue>
532+
</dev:defaultValue>
533+
</command:parameter>
516534
</command:syntaxItem>
517535
</command:syntax>
518536
<command:parameters>
537+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
538+
<maml:name>FormatAttribute</maml:name>
539+
<maml:description>
540+
<maml:para>The formatting used for unknown attributes.
541+
Any key or property in this object will be treated as a potential typename
542+
Any value will be the desired formatting.
543+
If the value is a [ScriptBlock], the [ScriptBlock] will be run.
544+
If the value is a [string], it will be expanded
545+
In either context, `$_` will be the current attribute.</maml:para>
546+
</maml:description>
547+
<command:parameterValue required="false" variableLength="true">Psobject</command:parameterValue>
548+
<dev:type>
549+
<maml:name>Psobject</maml:name>
550+
<maml:uri />
551+
</dev:type>
552+
<dev:defaultValue>
553+
</dev:defaultValue>
554+
</command:parameter>
519555
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
520556
<maml:name>GitHubDocRoot</maml:name>
521557
<maml:description>
@@ -640,7 +676,8 @@ If not provided, this will be the order they are defined in the formatter.</maml
640676
<maml:introduction>
641677
<maml:para> PS &gt; </maml:para>
642678
</maml:introduction>
643-
<dev:code> Get-MarkdownHelp Get-Help </dev:code>
679+
<dev:code> ##### Getting Markdown Help
680+
Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:code>
644681
<dev:remarks>
645682
</dev:remarks>
646683
</command:example>
@@ -666,7 +703,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
666703
<maml:description>
667704
<maml:para>Gets a script's references</maml:para>
668705
</maml:description>
669-
<dev:version>0.4.8</dev:version>
706+
<dev:version>0.4.9</dev:version>
670707
</command:details>
671708
<maml:description>
672709
<maml:para>Gets the external references of a given PowerShell command. These are the commands the script calls, and the types the script uses.</maml:para>
@@ -792,7 +829,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
792829
<maml:description>
793830
<maml:para>Gets a Script's story</maml:para>
794831
</maml:description>
795-
<dev:version>0.4.8</dev:version>
832+
<dev:version>0.4.9</dev:version>
796833
</command:details>
797834
<maml:description>
798835
<maml:para>Gets the Script's "Story"</maml:para>
@@ -955,7 +992,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
955992
<maml:description>
956993
<maml:para>Installs MAML into a module</maml:para>
957994
</maml:description>
958-
<dev:version>0.4.8</dev:version>
995+
<dev:version>0.4.9</dev:version>
959996
</command:details>
960997
<maml:description>
961998
<maml:para>Installs MAML into a module. </maml:para>
@@ -1309,7 +1346,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
13091346
<maml:description>
13101347
<maml:para>Determines the percentage of documentation</maml:para>
13111348
</maml:description>
1312-
<dev:version>0.4.8</dev:version>
1349+
<dev:version>0.4.9</dev:version>
13131350
</command:details>
13141351
<maml:description>
13151352
<maml:para>Determines the percentage of documentation in a given script</maml:para>
@@ -1452,7 +1489,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
14521489
<maml:description>
14531490
<maml:para>Saves a Module's MAML</maml:para>
14541491
</maml:description>
1455-
<dev:version>0.4.8</dev:version>
1492+
<dev:version>0.4.9</dev:version>
14561493
</command:details>
14571494
<maml:description>
14581495
<maml:para>Generates a Module's MAML file, and then saves it to the appropriate location.</maml:para>
@@ -1713,7 +1750,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
17131750
<maml:description>
17141751
<maml:para>Saves a Module's Markdown Help</maml:para>
17151752
</maml:description>
1716-
<dev:version>0.4.8</dev:version>
1753+
<dev:version>0.4.9</dev:version>
17171754
</command:details>
17181755
<maml:description>
17191756
<maml:para>Get markdown help for each command in a module and saves it to the appropriate location.</maml:para>
@@ -2006,6 +2043,24 @@ If not provided, all types of commands from the module will be saved as a markdo
20062043
<dev:defaultValue>
20072044
</dev:defaultValue>
20082045
</command:parameter>
2046+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2047+
<maml:name>FormatAttribute</maml:name>
2048+
<maml:description>
2049+
<maml:para>The formatting used for unknown attributes.
2050+
Any key or property in this object will be treated as a potential typename
2051+
Any value will be the desired formatting.
2052+
If the value is a [ScriptBlock], the [ScriptBlock] will be run.
2053+
If the value is a [string], it will be expanded
2054+
In either context, `$_` will be the current attribute.</maml:para>
2055+
</maml:description>
2056+
<command:parameterValue required="false" variableLength="true">Psobject</command:parameterValue>
2057+
<dev:type>
2058+
<maml:name>Psobject</maml:name>
2059+
<maml:uri />
2060+
</dev:type>
2061+
<dev:defaultValue>
2062+
</dev:defaultValue>
2063+
</command:parameter>
20092064
</command:syntaxItem>
20102065
</command:syntax>
20112066
<command:parameters>
@@ -2051,6 +2106,24 @@ Topic files that match this pattern will not be included.</maml:para>
20512106
<dev:defaultValue>
20522107
</dev:defaultValue>
20532108
</command:parameter>
2109+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2110+
<maml:name>FormatAttribute</maml:name>
2111+
<maml:description>
2112+
<maml:para>The formatting used for unknown attributes.
2113+
Any key or property in this object will be treated as a potential typename
2114+
Any value will be the desired formatting.
2115+
If the value is a [ScriptBlock], the [ScriptBlock] will be run.
2116+
If the value is a [string], it will be expanded
2117+
In either context, `$_` will be the current attribute.</maml:para>
2118+
</maml:description>
2119+
<command:parameterValue required="false" variableLength="true">Psobject</command:parameterValue>
2120+
<dev:type>
2121+
<maml:name>Psobject</maml:name>
2122+
<maml:uri />
2123+
</dev:type>
2124+
<dev:defaultValue>
2125+
</dev:defaultValue>
2126+
</command:parameter>
20542127
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
20552128
<maml:name>IncludeExtension</maml:name>
20562129
<maml:description>

‎HelpOut.PSA.ps1‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,7 +22,7 @@ Get-BskyActorProfile -Actor $env:AT_PROTOCOL_HANDLE -Cache | Out-Host
2222

2323
$isMergeToMain =
2424
($gitHubEvent.head_commit.message -match "Merge Pull Request #(?<PRNumber>\d+)") -and
25-
$gitHubEvent.ref -eq 'refs/heads/main'
25+
$gitHubEvent.ref -in 'refs/heads/main', 'refs/heads/master'
2626

2727
if ($isMergeToMain) {
2828
Import-Module .\HelpOut.psd1 -Global -PassThru | Out-Host
@@ -34,8 +34,10 @@ if ($isMergeToMain) {
3434
"#PowerShell people, help yourself to new bits: " |
3535
Get-Random
3636

37-
"$moduleAndVersion is out!"
38-
)
37+
"$moduleAndVersion is out!"
38+
39+
"https://github.com/StartAutomating/HelpOut"
40+
) -join ([Environment]::NewLine * 2)
3941

4042
Send-AtProto -Text $fullMessage -WebCard @{
4143
Url = "https://github.com/StartAutomating/HelpOut"

0 commit comments

Comments
 (0)