Merge pull request #209 from StartAutomating/HelpOut-Jekyll

HelpOut Jekyll
StartAutomating · Oct 13, 2024 · 5e14015 · 5e14015
2 parents 00ffbe5 + c3ce96a
commit 5e14015
Show file tree

Hide file tree

Showing 28 changed files with 1,076 additions and 47 deletions.
diff --git 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
@@ -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,15 +307,19 @@
 
                 # 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
 
                 # If -Wiki was passed, call Get-MarkDownHelp with -Wiki (this impacts link format)
                 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
@@ -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
@@ -8,7 +8,7 @@
       <maml:description>
         <maml:para>Gets MAML help</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Gets Markdown Help</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Gets a script's references</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Gets a Script's story</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Installs MAML into a module</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Determines the percentage of documentation</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Saves a Module's MAML</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Saves a Module's Markdown Help</maml:para>
       </maml:description>
-      <dev:version>0.5.4</dev:version>
+      <dev:version>0.5.5</dev:version>
     </command:details>
     <maml:description>
       <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>
           <dev:defaultValue>
           </dev:defaultValue>
         </command:parameter>
+        <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
+          <maml:name>JsonDataPath</maml:name>
+          <maml:description>
+            <maml:para>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`</maml:para>
+          </maml:description>
+          <command:parameterValue required="false" variableLength="true">String</command:parameterValue>
+          <dev:type>
+            <maml:name>String</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>
+          </dev:defaultValue>
+        </command:parameter>
+        <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
+          <maml:name>NoJson</maml:name>
+          <maml:description>
+            <maml:para>If set, will not output json data files.</maml:para>
+          </maml:description>
+          <command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
+          <dev:type>
+            <maml:name>Switch</maml:name>
+            <maml:uri />
+          </dev:type>
+          <dev:defaultValue>
+          </dev:defaultValue>
+        </command:parameter>
       </command:syntaxItem>
     </command:syntax>
     <command:parameters>
@@ -2574,6 +2602,21 @@ By default ```\.help\.txt$``` and ```\.md$```</maml:para>
         <dev:defaultValue>
         </dev:defaultValue>
       </command:parameter>
+      <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
+        <maml:name>JsonDataPath</maml:name>
+        <maml:description>
+          <maml:para>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`</maml:para>
+        </maml:description>
+        <command:parameterValue required="false" variableLength="true">String</command:parameterValue>
+        <dev:type>
+          <maml:name>String</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>
+        </dev:defaultValue>
+      </command:parameter>
       <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
         <maml:name>Module</maml:name>
         <maml:description>
@@ -2587,6 +2630,19 @@ By default ```\.help\.txt$``` and ```\.md$```</maml:para>
         <dev:defaultValue>
         </dev:defaultValue>
       </command:parameter>
+      <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
+        <maml:name>NoJson</maml:name>
+        <maml:description>
+          <maml:para>If set, will not output json data files.</maml:para>
+        </maml:description>
+        <command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
+        <dev:type>
+          <maml:name>Switch</maml:name>
+          <maml:uri />
+        </dev:type>
+        <dev:defaultValue>
+        </dev:defaultValue>
+      </command:parameter>
       <command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
         <maml:name>NoValidValueEnumeration</maml:name>
         <maml:description>

diff --git 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
 
 ---