Skip to content

Commit 5e14015

Browse files
StartAutomatingStartAutomating
authored
Merge pull request #209 from StartAutomating/HelpOut-Jekyll
HelpOut Jekyll
2 parents 00ffbe5 + c3ce96a commit 5e14015

28 files changed

+1076
-47
lines changed

‎CHANGELOG.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,18 @@
1+
### HelpOut 0.5.5:
2+
3+
* Save-MarkdownHelp `-JsonDataPath/-NoJson` (#208, #179)
4+
* Extending `HelpInfo`:
5+
* `HelpInfo.ToJson` (#205)
6+
* `HelpInfo.get_Note` (#206)
7+
* `HelpInfo.SaveJson` (#207)
8+
* Extended Type Help Improvements:
9+
* Fixing Summary Titles (#202)
10+
* Separating Script Properties (#203)
11+
* Special Thanks:
12+
* @potatoqualitee
13+
14+
---
15+
116
### HelpOut 0.5.4:
217

318
* HelpOut containerization

‎Commands/Save-MarkdownHelp.ps1‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -162,7 +162,17 @@
162162
# If the value is a [string], it will be expanded
163163
# In either context, `$_` will be the current attribute.
164164
[PSObject]
165-
$FormatAttribute
165+
$FormatAttribute,
166+
167+
# The path where json data should be located.
168+
# If this is not provided, it will be assumed to be a subdirectory of the -OutputPath.
169+
# Specifically, it will be assumed to be: `$OutputPath/_data/Help`
170+
[string]
171+
$JsonDataPath,
172+
173+
# If set, will not output json data files.
174+
[switch]
175+
$NoJson
166176
)
167177

168178
begin {
@@ -252,6 +262,12 @@
252262
$null = New-Item -ItemType Directory -Path $OutputPath # create it.
253263
}
254264

265+
if (-not $PSBoundParameters.JsonDataPath) {
266+
$JsonDataPath = Join-Path $OutputPath '_data' | Join-Path -ChildPath 'Help'
267+
} else {
268+
$JsonDataPath = $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($JsonDataPath)
269+
}
270+
255271
if ((-not $ExcludeSubModule) -and (-not $IncludeSubmodule)) {
256272
Push-Location $theModuleRoot
257273

@@ -291,15 +307,19 @@
291307

292308
# Determine the output path for each item.
293309
$docOutputPath = Join-Path $outputPath ($cmd.Name + '.md')
310+
if ($JsonDataPath) {
311+
$jsonOutputPath = Join-Path $JsonDataPath ($cmd.Name + '.json')
312+
}
294313
# Prepare a splat for this command by copying out base splat.
295314
$getMarkdownHelpSplat = @{Name="$cmd"} + $getMarkdownHelpSplatBase
296315

297316
# If -Wiki was passed, call Get-MarkDownHelp with -Wiki (this impacts link format)
298317
if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki }
299318
# otherwise, pass down the parent of $OutputPath.
300319
else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"}
301-
302-
$markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat
320+
321+
$markdownTopic = Get-MarkdownHelp @getMarkdownHelpSplat
322+
303323
$markdownFile =
304324
if ($markdownTopic.Save) {
305325
$markdownTopic.Save($docOutputPath)
@@ -312,6 +332,20 @@
312332
$markdownFile
313333
}
314334
}
335+
if ($JsonDataPath -and -not $NoJson) {
336+
$jsonFile =
337+
if ($markdownTopic.SaveJson) {
338+
$markdownTopic.SaveJson($jsonOutputPath)
339+
} else { $null }
340+
341+
if ($jsonFile) {
342+
$filesChanged += $jsonFile
343+
344+
if ($PassThru) { # If -PassThru was provided, get the path.
345+
$jsonFile
346+
}
347+
}
348+
}
315349
}
316350

317351
if ($Command) {

‎Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1‎

Lines changed: 38 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,12 @@ $punctuationNotDashOrUnderscore = '[\p{P}-[\-_]]'
3535
# go over each extended type
3636
foreach ($extendedType in $extendedTypeNames) {
3737
# and get the actual type data
38-
$actualTypeData = Get-TypeData -TypeName $extendedType
38+
$actualTypeData = Get-TypeData -TypeName $extendedType
39+
40+
# We will want to keep track of methods and properties in order,
41+
# so we don't have to sort or resolve them later.
42+
$methodsByName = [Ordered]@{}
43+
$propertiesByName = [Ordered]@{}
3944

4045
$memberFiles =
4146
@(foreach ($member in $actualTypeData.Members.Values) {
@@ -74,16 +79,33 @@ foreach ($extendedType in $extendedTypeNames) {
7479

7580
$TopicPathSegments = @(
7681
$extendedType -split $punctuationNotDashOrUnderscore
77-
$member.Name -replace $replaceMostPunctuation
82+
if ($getSetNothing) {
83+
$getSetNothing + ($member.Name -replace $replaceMostPunctuation)
84+
} else {
85+
$member.Name -replace $replaceMostPunctuation
86+
}
7887
)
7988
$etsDocPath = Join-Path $outputPath "$(
8089
$TopicPathSegments -join [IO.Path]::DirectorySeparatorChar
8190
).md"
8291

8392
# .Save it,
84-
$markdownHelp.Save($etsDocPath)
85-
# and remove the temporary function (it would have gone out of scope anyways)
93+
$memberFile = $markdownHelp.Save($etsDocPath)
94+
# and remove the temporary function (it would have gone out of scope anyways).
8695
$ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)")
96+
97+
# Emit the member file
98+
$memberFile
99+
100+
if ($getSetNothing) {
101+
if (-not $propertiesByName[$member.Name]) {
102+
$propertiesByName[$member.Name] = $memberFile
103+
} else {
104+
$propertiesByName[$member.Name] = @($propertiesByName[$member.Name]) + $memberFile
105+
}
106+
} else {
107+
$methodsByName[$member.Name] = $memberFile
108+
}
87109
}
88110

89111

@@ -106,6 +128,7 @@ foreach ($extendedType in $extendedTypeNames) {
106128
# If the type had a .README member, include it inline
107129
if ($actualTypeData.Members -and $actualTypeData.Members["README"].Value) {
108130
$actualTypeData.Members["README"].Value
131+
[Environment]::NewLine
109132
}
110133

111134
# Sort the member files into properties and methods
@@ -119,21 +142,27 @@ foreach ($extendedType in $extendedTypeNames) {
119142
"### Script Properties"
120143
[Environment]::NewLine
121144
# and be sorted by property name.
122-
foreach ($memberFile in $propertyMemberFiles | Sort-Object { $_.Name -replace $getSetFile}) {
123-
"* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
145+
foreach ($memberKeyValue in $propertiesByName.GetEnumerator()) {
146+
# If there are multiple files for a property, it's got a get and a set.
147+
if ($memberKeyValue.Value -is [array]) {
148+
"* [get_$($memberKeyValue.Key)]($($memberKeyValue.Value[0].Name))"
149+
"* [set_$($memberKeyValue.Key)]($($memberKeyValue.Value[1].Name))"
150+
} else {
151+
"* [get_$($memberKeyValue.Key)]($($memberKeyValue.Value.Name))"
152+
}
124153
}
154+
[Environment]::NewLine
125155
}
126156
# Methods should come after properties.
127157
if ($methodMemberFiles) {
128158
"### Script Methods"
129159
[Environment]::NewLine
130160
# and will be sorted alphabetically.
131-
foreach ($memberFile in $methodMemberFiles) {
132-
"* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
161+
foreach ($memberKeyValue in $methodsByName.GetEnumerator()) {
162+
"* [$($memberKeyValue.Key)()]($($memberKeyValue.Value.Name))"
133163
}
134164
}
135165
}
136-
137166
) -join ([Environment]::NewLine)
138167

139168
$ExtendedTypeDocContent | Set-Content -Path $ExtendedTypeDocFile

‎HelpOut-Help.xml‎

Lines changed: 64 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.5.4</dev:version>
11+
<dev:version>0.5.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>
@@ -535,7 +535,7 @@ If not provided, all types of commands from the module will be saved as a markdo
535535
<maml:description>
536536
<maml:para>Gets Markdown Help</maml:para>
537537
</maml:description>
538-
<dev:version>0.5.4</dev:version>
538+
<dev:version>0.5.5</dev:version>
539539
</command:details>
540540
<maml:description>
541541
<maml:para>Gets Help for a given command, in Markdown</maml:para>
@@ -838,7 +838,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
838838
<maml:description>
839839
<maml:para>Gets a script's references</maml:para>
840840
</maml:description>
841-
<dev:version>0.5.4</dev:version>
841+
<dev:version>0.5.5</dev:version>
842842
</command:details>
843843
<maml:description>
844844
<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>
@@ -964,7 +964,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
964964
<maml:description>
965965
<maml:para>Gets a Script's story</maml:para>
966966
</maml:description>
967-
<dev:version>0.5.4</dev:version>
967+
<dev:version>0.5.5</dev:version>
968968
</command:details>
969969
<maml:description>
970970
<maml:para>Gets the Script's "Story"</maml:para>
@@ -1127,7 +1127,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
11271127
<maml:description>
11281128
<maml:para>Installs MAML into a module</maml:para>
11291129
</maml:description>
1130-
<dev:version>0.5.4</dev:version>
1130+
<dev:version>0.5.5</dev:version>
11311131
</command:details>
11321132
<maml:description>
11331133
<maml:para>Installs MAML into a module. </maml:para>
@@ -1563,7 +1563,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
15631563
<maml:description>
15641564
<maml:para>Determines the percentage of documentation</maml:para>
15651565
</maml:description>
1566-
<dev:version>0.5.4</dev:version>
1566+
<dev:version>0.5.5</dev:version>
15671567
</command:details>
15681568
<maml:description>
15691569
<maml:para>Determines the percentage of documentation in a given script</maml:para>
@@ -1706,7 +1706,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
17061706
<maml:description>
17071707
<maml:para>Saves a Module's MAML</maml:para>
17081708
</maml:description>
1709-
<dev:version>0.5.4</dev:version>
1709+
<dev:version>0.5.5</dev:version>
17101710
</command:details>
17111711
<maml:description>
17121712
<maml:para>Generates a Module's MAML file, and then saves it to the appropriate location.</maml:para>
@@ -2048,7 +2048,7 @@ If not provided, all types of commands from the module will be saved as a markdo
20482048
<maml:description>
20492049
<maml:para>Saves a Module's Markdown Help</maml:para>
20502050
</maml:description>
2051-
<dev:version>0.5.4</dev:version>
2051+
<dev:version>0.5.5</dev:version>
20522052
</command:details>
20532053
<maml:description>
20542054
<maml:para>Get markdown help for each command in a module and saves it to the appropriate location.</maml:para>
@@ -2414,6 +2414,34 @@ In either context, `$_` will be the current attribute.</maml:para>
24142414
<dev:defaultValue>
24152415
</dev:defaultValue>
24162416
</command:parameter>
2417+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2418+
<maml:name>JsonDataPath</maml:name>
2419+
<maml:description>
2420+
<maml:para>The path where json data should be located.
2421+
If this is not provided, it will be assumed to be a subdirectory of the -OutputPath.
2422+
Specifically, it will be assumed to be: `$OutputPath/_data/Help`</maml:para>
2423+
</maml:description>
2424+
<command:parameterValue required="false" variableLength="true">String</command:parameterValue>
2425+
<dev:type>
2426+
<maml:name>String</maml:name>
2427+
<maml:uri />
2428+
</dev:type>
2429+
<dev:defaultValue>
2430+
</dev:defaultValue>
2431+
</command:parameter>
2432+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2433+
<maml:name>NoJson</maml:name>
2434+
<maml:description>
2435+
<maml:para>If set, will not output json data files.</maml:para>
2436+
</maml:description>
2437+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2438+
<dev:type>
2439+
<maml:name>Switch</maml:name>
2440+
<maml:uri />
2441+
</dev:type>
2442+
<dev:defaultValue>
2443+
</dev:defaultValue>
2444+
</command:parameter>
24172445
</command:syntaxItem>
24182446
</command:syntax>
24192447
<command:parameters>
@@ -2574,6 +2602,21 @@ By default ```\.help\.txt$``` and ```\.md$```</maml:para>
25742602
<dev:defaultValue>
25752603
</dev:defaultValue>
25762604
</command:parameter>
2605+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2606+
<maml:name>JsonDataPath</maml:name>
2607+
<maml:description>
2608+
<maml:para>The path where json data should be located.
2609+
If this is not provided, it will be assumed to be a subdirectory of the -OutputPath.
2610+
Specifically, it will be assumed to be: `$OutputPath/_data/Help`</maml:para>
2611+
</maml:description>
2612+
<command:parameterValue required="false" variableLength="true">String</command:parameterValue>
2613+
<dev:type>
2614+
<maml:name>String</maml:name>
2615+
<maml:uri />
2616+
</dev:type>
2617+
<dev:defaultValue>
2618+
</dev:defaultValue>
2619+
</command:parameter>
25772620
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
25782621
<maml:name>Module</maml:name>
25792622
<maml:description>
@@ -2587,6 +2630,19 @@ By default ```\.help\.txt$``` and ```\.md$```</maml:para>
25872630
<dev:defaultValue>
25882631
</dev:defaultValue>
25892632
</command:parameter>
2633+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2634+
<maml:name>NoJson</maml:name>
2635+
<maml:description>
2636+
<maml:para>If set, will not output json data files.</maml:para>
2637+
</maml:description>
2638+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2639+
<dev:type>
2640+
<maml:name>Switch</maml:name>
2641+
<maml:uri />
2642+
</dev:type>
2643+
<dev:defaultValue>
2644+
</dev:defaultValue>
2645+
</command:parameter>
25902646
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
25912647
<maml:name>NoValidValueEnumeration</maml:name>
25922648
<maml:description>

‎HelpOut.psd1‎

Lines changed: 13 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -7,32 +7,26 @@
77
ModuleToProcess='HelpOut.psm1'
88
FormatsToProcess='HelpOut.format.ps1xml'
99
TypesToProcess='HelpOut.types.ps1xml'
10-
ModuleVersion='0.5.4'
10+
ModuleVersion='0.5.5'
1111
PrivateData = @{
1212
PSData = @{
1313
ProjectURI = 'https://github.com/StartAutomating/HelpOut'
1414
LicenseURI = 'https://github.com/StartAutomating/HelpOut/blob/master/LICENSE'
1515

16-
Tags = 'Markdown', 'Help','PowerShell'
16+
Tags = 'Markdown', 'Help', 'PowerShell'
1717
ReleaseNotes = @'
18-
### HelpOut 0.5.4:
18+
### HelpOut 0.5.5:
1919
20-
* HelpOut containerization
21-
* Dockerfile (#182)
22-
* Publishing to `https://ghcr.io/startautomating/helpout` (#183)
23-
* Container.init.ps1 (#191)
24-
* Container.start.ps1 (#193)
25-
* Container.stop.ps1 (#194)
26-
* Get/Save-Maml -IncludeAlias/-SkipCommandType (#178) (thanks @potatoqualitee ! )
27-
* Get-MarkdownHelp keeps alias names (#200)
28-
* HelpOut repository improvements
29-
* Organizing Files (#184, #185, #186, #187)
30-
* HelpOut is now exported as `$HelpOut` (#188)
31-
* HelpOut's root is now exported as `HelpOut:` (#189)
32-
* Extended Type Help Improvement:
33-
* Extended Member Titles (#198)
34-
* Fixing Grouping (#197)
35-
* Fixing Type File Naming (#196)
20+
* Save-MarkdownHelp `-JsonDataPath/-NoJson` (#208, #179)
21+
* Extending `HelpInfo`:
22+
* `HelpInfo.ToJson` (#205)
23+
* `HelpInfo.get_Note` (#206)
24+
* `HelpInfo.SaveJson` (#207)
25+
* Extended Type Help Improvements:
26+
* Fixing Summary Titles (#202)
27+
* Separating Script Properties (#203)
28+
* Special Thanks:
29+
* @potatoqualitee
3630
3731
---
3832

0 commit comments

Comments
 (0)