Skip to content

Commit bc2ae8b

Browse files
StartAutomatingStartAutomating
authored
Merge pull request #127 from StartAutomating/HelpOut-Extensibility
HelpOut 0.4.5
2 parents 2c2f875 + 08fc151 commit bc2ae8b

19 files changed

Lines changed: 842 additions & 302 deletions

‎.github/FUNDING.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
github: [StartAutomating]

‎CHANGELOG.md‎

Lines changed: 38 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,21 @@
1-
### 0.4.4
1+
### HelpOut 0.4.5:
2+
3+
* You can now sponsor HelpOut (#126)
4+
* Added ScriptMethods to PowerShell.Markdown.Help (#125)
5+
* Now allowing Save-MarkDownHelp to be extended by any HelpOut.SaveMarkdownHelp file or function (#123)
6+
* This is used in HelpOut.SaveMarkdownHelp.ExtendedTypes, which auto documents extended types (#101)
7+
8+
---
9+
10+
### HelpOut 0.4.4:
211

312
* Improved HelpOut action output (Fixes #121)
413
* HelpOut has a logo (Fixes #120)
514
* Save-MarkdownHelp now trims content (Fixes #119)
615

716
---
817

9-
### 0.4.3
18+
### HelpOut 0.4.3:
1019

1120
* Action Improvements:
1221
* Not obeying -InstallModule if a local module is found (Fixes #113)
@@ -15,7 +24,7 @@
1524

1625
---
1726

18-
### 0.4.2
27+
### HelpOut 0.4.2:
1928

2029
* Markdown Help Improvements:
2130
* Adding Aliases (Fixes #111)
@@ -34,15 +43,14 @@
3443

3544
---
3645

37-
38-
### 0.4.1
46+
### HelpOut 0.4.1:
3947

4048
* Parameter Properties are now rendered as a table (Fixes #98)
4149
* Save-MarkdownHelp: Adding -ExcludeFile (Fixes #97)
4250

4351
---
4452

45-
### 0.4
53+
### HelpOut 0.4:
4654

4755
* Get/Save-MarkdownHelp:
4856
* Adding -YamlHeaderInformationType and including [Reflection.AssemblyMetaData] attributes (Fixes #93)
@@ -51,80 +59,83 @@
5159

5260
---
5361

54-
### 0.3.9
62+
### HelpOut 0.3.9:
5563

5664
* No longer attempting to repair links if the file is not markdown (Fixes #88)
5765

5866
---
5967

60-
### 0.3.8
68+
### HelpOut 0.3.8:
6169

6270
* YAML Header is now optional (with -IncludeYamlHeader) (Fixes #80)
6371
* Save-MarkdownHelp trims content (Fixes #85)
6472

6573
---
6674

67-
### 0.3.7
75+
### HelpOut 0.3.7:
6876

6977
All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fixes #80)
7078

7179
---
7280

73-
### 0.3.6
81+
### HelpOut 0.3.6:
7482
* Improvements to [OutputType] support (Fixes #78)
7583
* GitHub Action No Longer Runs when not on a branch (Fixes #77)
7684

7785
---
7886

79-
### 0.3.5
87+
### HelpOut 0.3.5:
8088
* Markdown Help Improvements: Escaping Example Code (Fixes #75)
8189

8290
---
8391

84-
### 0.3.4
92+
### HelpOut 0.3.4:
8593
* Fixing accidental heading names in .Link and parameter properties (Fixes #73)
8694

8795
---
8896

89-
### 0.3.3
97+
### HelpOut 0.3.3:
9098
* Markdown Help now uses fewer tables (improves default GitHub Page rendering) (fixes #71)
9199

92100
---
93101

94-
### 0.3.2
102+
### HelpOut 0.3.2:
95103
* Save-MarkdownHelp Bugfix (Fixes #69)
96104

97105
---
98106

99-
### 0.3.1
107+
### HelpOut 0.3.1:
100108
* Save-MarkdownHelp:
101109
* Can now -ReplaceLink (Fixes #66)
102110
* -ReplaceLink will always replace -OutputPath (Fixes #67)
103111
* Changing Aliases for -SkipCommandType (Fixes #65)
104112

105113
---
106114

107-
### 0.3:
115+
116+
### HelpOut 0.3:
108117
* Get-MarkdownHelp: Fixing Property Table rendering issues with ValidValues (#58)
109118
* Workflow improvements: Building formatting / types in CI/CD (#63)
119+
110120
---
111-
### 0.2.9:
121+
122+
### HelpOut 0.2.9:
112123
* Get-MarkdownHelp: Fixing Property Table rendering issues with ValidValues (#58)
113124
* Action improvements:
114125
* Pulling just before push (#59)
115126
* Improving username / email detection (#60)
116127

117128
---
118129

119-
### 0.2.8:
130+
### HelpOut 0.2.8:
120131
* Save-MarkdownHelp:
121132
* Adding -ExcludeTopic (#55)
122133
* -IncludeTopic excludes deeply nested topics (#54)
123134
* -IncludeExtension default now includes .svg files (#53)
124135

125136
---
126137

127-
### 0.2.7
138+
### HelpOut 0.2.7:
128139
* Save-MarkdownHelp:
129140
* Adding -Command, -ReplaceCommandName, -ReplaceCommandNameWith (#45)
130141
* Fixing -ReplaceScriptName issue (#46)
@@ -134,7 +145,7 @@ All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fix
134145

135146
---
136147

137-
### 0.2.6
148+
### HelpOut 0.2.6:
138149
* Save-MarkdownHelp:
139150
* Improving Inline Documentation
140151
* Allowing -ScriptPath to be a Regex (#41)
@@ -143,7 +154,7 @@ All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fix
143154

144155
---
145156

146-
### 0.2.5
157+
### HelpOut 0.2.5:
147158
* Save-MarkdownHelp:
148159
* Adding -IncludeExtension (#35)
149160
* Applying -PassThru to -IncludeTopic (#34)
@@ -152,29 +163,29 @@ All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fix
152163

153164
---
154165

155-
### 0.2.4
166+
### HelpOut 0.2.4:
156167
* Save-MarkdownHelp:
157168
* Adding -SkipCommandType (#29)
158169
* -ScriptPath now allows wildcards (#28)
159170
* Formatting now Handles Arrays of Enums (#30)
160171

161172
---
162173

163-
### 0.2.3
174+
### HelpOut 0.2.3:
164175
* Get/Save-MarkdownHelp: Support for -NoValidValueEnumeration (re #25)
165176
* Save-MarkdownHelp: Adding -IncludeTopic (Fixes #24, #26)
166177
* Adding ValidateSet/Enum Formatting for Markdown Help (Fixing #25)
167178

168179

169180
---
170181

171-
### 0.2.2
182+
### HelpOut 0.2.2:
172183
* Fixing issue generating docs (#22)
173184
* HelpOut Action Fix (#20)
174185

175186
---
176187

177-
### 0.2.1
188+
### HelpOut 0.2.1:
178189
* Get/Save-MarkdownHelp: Support for -SectionOrder (#19)
179190
* Save-MarkdownHelp: Adding -Passthru (#17). Converting Markdown Help into a string (#18)
180191
* Get-MarkdownHelp: Returning Object (#18)
@@ -184,7 +195,7 @@ All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fix
184195

185196
---
186197

187-
### 0.2
198+
### HelpOut 0.2:
188199
* Adding Install-MAML (#1/ #7)
189200
* Adding Get-MarkdownHelp (#4)
190201
* Adding Save-MarkdownHelp (#10)
@@ -194,4 +205,4 @@ All Markdown help now includes a YAML Header unless -NoYAMLHeader is passed (Fix
194205
* Adding Get-ScriptReference (#2)
195206
* Renmaing ConvertTo-MAML->Get-MAML
196207

197-
---
208+
---

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

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -322,9 +322,11 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co
322322

323323
$sectionCounter = 0
324324
foreach ($sectionName in $orderOfSections) {
325+
325326
$sectionCounter++
326327
$sectionContent =
327-
if ($MarkdownSections.$sectionName -is [ScriptBlock]) {
328+
if ($MarkdownSections.$sectionName -is [ScriptBlock] -and
329+
$helpObject.HideSections -notcontains $sectionName) {
328330
& $MarkdownSections.$sectionName
329331
} else { $null }
330332
if ($sectionContent) {

‎HelpOut-Help.xml‎

Lines changed: 8 additions & 8 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.4</dev:version>
11+
<dev:version>0.4.5</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.4</dev:version>
403+
<dev:version>0.4.5</dev:version>
404404
</command:details>
405405
<maml:description>
406406
<maml:para>Gets Help for a given command, in Markdown</maml:para>
@@ -666,7 +666,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
666666
<maml:description>
667667
<maml:para>Gets a script's references</maml:para>
668668
</maml:description>
669-
<dev:version>0.4.4</dev:version>
669+
<dev:version>0.4.5</dev:version>
670670
</command:details>
671671
<maml:description>
672672
<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 +792,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
792792
<maml:description>
793793
<maml:para>Gets a Script's story</maml:para>
794794
</maml:description>
795-
<dev:version>0.4.4</dev:version>
795+
<dev:version>0.4.5</dev:version>
796796
</command:details>
797797
<maml:description>
798798
<maml:para>Gets the Script's "Story"</maml:para>
@@ -955,7 +955,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
955955
<maml:description>
956956
<maml:para>Installs MAML into a module</maml:para>
957957
</maml:description>
958-
<dev:version>0.4.4</dev:version>
958+
<dev:version>0.4.5</dev:version>
959959
</command:details>
960960
<maml:description>
961961
<maml:para>Installs MAML into a module. </maml:para>
@@ -1309,7 +1309,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
13091309
<maml:description>
13101310
<maml:para>Determines the percentage of documentation</maml:para>
13111311
</maml:description>
1312-
<dev:version>0.4.4</dev:version>
1312+
<dev:version>0.4.5</dev:version>
13131313
</command:details>
13141314
<maml:description>
13151315
<maml:para>Determines the percentage of documentation in a given script</maml:para>
@@ -1452,7 +1452,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
14521452
<maml:description>
14531453
<maml:para>Saves a Module's MAML</maml:para>
14541454
</maml:description>
1455-
<dev:version>0.4.4</dev:version>
1455+
<dev:version>0.4.5</dev:version>
14561456
</command:details>
14571457
<maml:description>
14581458
<maml:para>Generates a Module's MAML file, and then saves it to the appropriate location.</maml:para>
@@ -1713,7 +1713,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
17131713
<maml:description>
17141714
<maml:para>Saves a Module's Markdown Help</maml:para>
17151715
</maml:description>
1716-
<dev:version>0.4.4</dev:version>
1716+
<dev:version>0.4.5</dev:version>
17171717
</command:details>
17181718
<maml:description>
17191719
<maml:para>Get markdown help for each command in a module and saves it to the appropriate location.</maml:para>

‎HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
<#
2+
.SYNOPSIS
3+
Saves Markdown Help for Extended Types
4+
.DESCRIPTION
5+
This saves Markdown Help from Extended Types (types.ps1xml) files.
6+
#>
7+
param(
8+
# The module that contains extended types
9+
$Module
10+
)
11+
12+
# If there is no module, return
13+
if (-not $module) { return }
14+
15+
# If the module is a string, get the actual module
16+
if ($module -is [string]) {
17+
$module = Get-Module -Name $module
18+
}
19+
20+
# If there were not exported type files, return
21+
if (-not $module.ExportedTypeFiles) {
22+
return
23+
}
24+
25+
# Get each extended type name
26+
$extendedTypeNames =
27+
@($module.ExportedTypeFiles) |
28+
Select-Xml //Type -Path { $_ } |
29+
Select-Object -ExpandProperty Node |
30+
Select-Object -ExpandProperty Name
31+
32+
# and be ready to replace most punctuation
33+
$replaceMostPunctuation = '[\p{P}-[\-\._]]'
34+
# go over each extended type
35+
foreach ($extendedType in $extendedTypeNames) {
36+
# and get the actual type data
37+
$actualTypeData = Get-TypeData -TypeName $extendedType
38+
foreach ($member in $actualTypeData.Members.Values) {
39+
# If the script looks like it does not have inline help, continue
40+
41+
42+
foreach ($potentialProperty in 'Script','GetScriptBlock','SetScriptBlock') {
43+
if ($member.$PotentialProperty -notlike '*<#*.synopsis*#>*') { continue }
44+
$markdownSplat = @{}
45+
# Create a temporary function to hold the help.
46+
$getSetNothing =
47+
if ($potentialProperty -eq 'GetScriptBlock') {
48+
"get_"
49+
}
50+
elseif ($potentialProperty -eq 'SetScriptBlock') {
51+
"set_"
52+
}
53+
elseif ($potentialProperty -eq 'Script') {
54+
''
55+
}
56+
$temporaryFunctionName = "$($extendedType).$GetSetNothing$($member.Name)" -replace $replaceMostPunctuation
57+
$markdownSplat.Rename = "$temporaryFunctionName()"
58+
$ExecutionContext.SessionState.PSVariable.Set("function:$($temporaryFunctionName)", $member.$PotentialProperty)
59+
# Then Get-MarkdownHelp,
60+
$markdownHelp = Get-MarkdownHelp -Name $temporaryFunctionName @getMarkdownHelpSplatBase @markdownSplat
61+
$markdownHelp.HideSection("Syntax")
62+
# .Save it,
63+
$markdownHelp.Save((Join-Path $outputPath "$($temporaryFunctionName).md"))
64+
# and remove the temporary function (it would have gone out of scope anyways)
65+
$ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)")
66+
}
67+
68+
69+
}
70+
}

‎HelpOut.format.ps1xml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -435,9 +435,11 @@ If the command sets a ```[ConfirmImpact("Medium")]``` which is lower than ```$co
435435

436436
$sectionCounter = 0
437437
foreach ($sectionName in $orderOfSections) {
438+
438439
$sectionCounter++
439440
$sectionContent =
440-
if ($MarkdownSections.$sectionName -is [ScriptBlock]) {
441+
if ($MarkdownSections.$sectionName -is [ScriptBlock] -and
442+
$helpObject.HideSections -notcontains $sectionName) {
441443
&amp; $MarkdownSections.$sectionName
442444
} else { $null }
443445
if ($sectionContent) {

0 commit comments

Comments
 (0)