HelpOut 0.4.8

.github/workflows/TestReleaseAndPublish.yml

@@ -590,4 +590,9 @@ jobs:
         if: ${{github.ref_name != 'master'}}
         uses: ./
         id: HelpOutBranch
-
+      - name: PSA
+        uses: StartAutomating/PSA@main
+        id: PSA
+env: 
+  AT_PROTOCOL_APP_PASSWORD: ${{ secrets.AT_PROTOCOL_APP_PASSWORD }}
+  AT_PROTOCOL_HANDLE: mrpowershell.bsky.social

CHANGELOG.md

@@ -1,3 +1,20 @@
+### HelpOut 0.4.8:
+
+* Markdown Help Improvements:
+  * Fixing Long Examples (Fixes #141)
+  * Allowing first comment lines in an example to be markdown (#143)
+  * Also, switching numbered example headings to blockquotes
+* Save-MarkdownHelp updates:
+  * Fixing Piping Behavior (#140)
+  * Not Saving to illegal windows paths (#132)
+* Improving Extended Types Doc Generation
+  * Now puts extended type documentation into subfolders (#135)
+  * Also, generates a summary file for each type (#133)
+* Updating links to Microsoft modules (#142)
+* Integrating PSA into HelpOut (#144)
+
+---
+
 ### HelpOut 0.4.7:
 
 * Get-MarkdownHelp:  Automatically renaming help about aliases (Fixes #130)

Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1

@@ -31,15 +31,16 @@ $extendedTypeNames =
 
 # and be ready to replace most punctuation
 $replaceMostPunctuation = '[\p{P}-[\-\._]]'
+$punctuationNotDashOrUnderscore = '[\p{P}-[\-_]]'
 # go over each extended type
 foreach ($extendedType in $extendedTypeNames) {
     # and get the actual type data
-    $actualTypeData = Get-TypeData -TypeName $extendedType
-    foreach ($member in $actualTypeData.Members.Values) {
-        # If the script looks like it does not have inline help, continue
-
+    $actualTypeData = Get-TypeData -TypeName $extendedType    
 
+    $memberFiles = 
+    @(foreach ($member in $actualTypeData.Members.Values) {
         foreach ($potentialProperty in 'Script','GetScriptBlock','SetScriptBlock') {
+            # If the script looks like it does not have inline help, continue        
             if ($member.$PotentialProperty -notlike '*<#*.synopsis*#>*') { continue }
             $markdownSplat = @{}
             # Create a temporary function to hold the help.
@@ -53,6 +54,7 @@ foreach ($extendedType in $extendedTypeNames) {
                 elseif ($potentialProperty -eq 'Script') {
                     ''                    
                 }
+            $fullExtendedTypeInfo = "$($extendedType).$GetSetNothing$($member.Name)"
             $temporaryFunctionName = "$($extendedType).$GetSetNothing$($member.Name)" -replace $replaceMostPunctuation
             $markdownSplat.Rename = "$temporaryFunctionName()"        
             $ExecutionContext.SessionState.PSVariable.Set("function:$($temporaryFunctionName)", $member.$PotentialProperty)
@@ -63,12 +65,57 @@ foreach ($extendedType in $extendedTypeNames) {
                 continue    
             }
             $markdownHelp.HideSection("Syntax")
+
+            $etsDocPath = Join-Path $outputPath "$(
+                @($fullExtendedTypeInfo -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar
+            ).md"
+
             # .Save it,
-            $markdownHelp.Save((Join-Path $outputPath "$($temporaryFunctionName).md"))            
+            $markdownHelp.Save($etsDocPath)            
             # and remove the temporary function (it would have gone out of scope anyways)
             $ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)")
         }
 
 
+    })
+
+    $ExtendedTypeDocFile = Join-Path $outputPath "$(
+        ($extendedType -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar
+    )$([IO.Path]::DirectorySeparatorChar)README.md"
+
+    $getSetFile = '\.(?>get|set)_'
+    $ExtendedTypeDocContent = @(
+        "## $extendedType"
+        [Environment]::NewLine
+
+        if ($actualTypeData.Members -and $actualTypeData.Members["README"].Value) {
+            $actualTypeData.Members["README"].Value
+        }
+
+
+        $propertyMemberFiles = $memberFiles | Where-Object Name -Match $getSetFile
+        if ($propertyMemberFiles) {
+            "### Script Properties"
+            [Environment]::NewLine
+            foreach ($memberFile in $propertyMemberFiles | Sort-Object { $_.Name -replace $getSetFile}) {                
+                "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
+            }
+        }
+        $methodMemberFiles = $memberFiles | Where-Object Name -NotMatch $getSetFile
+        if ($methodMemberFiles) {
+            "### Script Methods"
+            [Environment]::NewLine
+            foreach ($memberFile in $methodMemberFiles) {
+                "* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
+            }
+        }
+
+    )  -join ([Environment]::NewLine)
+
+    $ExtendedTypeDocContent | Set-Content -Path $ExtendedTypeDocFile
+    if ($?) {
+        Get-Item -Path $ExtendedTypeDocFile
     }
+
+    $memberFiles
 }

Formatting/PowerShell.Markdown.Help.format.ps1

@@ -34,7 +34,7 @@
                         }
                         elseif ($linkedCmd -and ($linkedCmd.Module -like 'microsoft.*' -or $linkedCmd.Source -like 'microsoft.*')) {
                             $linkSrc = if ($linkedCmd.Module) { $linkedCmd.Module} else { $linkedCmd.Source }
-                            "https://docs.microsoft.com/powershell/module/$linkSrc/$linkedCmd"
+                            "https://learn.microsoft.com/powershell/module/$linkSrc/$linkedCmd"
                         } elseif ($helpObject.WikiLink) {
                             $nav.LinkText
                         } elseif ($null -ne $helpObject.DocLink) {
@@ -54,17 +54,49 @@
         Examples = {
             if ($helpObject.Examples) {
                 Format-Markdown -Heading "Examples" -headingsize 3
-
+
+
                 foreach ($example in $helpObject.Examples.Example) {
-                    Format-Markdown -Heading ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') -HeadingSize 4
-
-                    if ($example.Code) {
-                        $example.Code | Format-Markdown -CodeLanguage PowerShell
-                    }
-
-                    if ($example.Remarks) {
-                        ($example.Remarks | Out-String -Width 1mb).Trim()
-                    }
+
+                    # Combine the code and remarks
+                    $exampleLines = 
+                        @(
+                            $example.Code
+                            foreach ($remark in $example.Remarks.text) {
+                                if (-not $remark) { continue }
+                                $remark
+                            }
+                        ) -join ([Environment]::NewLine) -split '(?>\r\n|\n)' # and split into lines
+
+                    # Anything until the first non-comment line is a markdown predicate to the example
+                    $nonCommentLine = $false
+                    $markdownLines = @()
+
+                    # Go thru each line in the example as part of a loop
+                    $codeBlock = @(foreach ($exampleLine in $exampleLines) {
+                        if ($exampleLine -match '^\#' -and -not $nonCommentLine) {
+                            $markdownLines += $exampleLine -replace '^\#' -replace '^\s+'
+                        } else {
+                            $nonCommentLine = $true
+                            $exampleLine
+                        }
+                    }) -join [Environment]::NewLine
+                    @(
+                        if ($markdownLines) {
+                            $markdownLines -join [Environment]::NewLine
+                        } else {
+                            Format-Markdown -BlockQuote -InputObject ($example.Title -replace '^[-\s]+' -replace '[-\s]+$')
+                        }
+
+                        if ($codeBlock) {
+                            $codeBlockAsScriptBlock = try { [ScriptBlock]::Create($codeBlock) } catch { $false }
+                            if ($codeBlockAsScriptBlock) {
+                                $codeBlockAsScriptBlock | Format-Markdown
+                            } else {
+                                $codeBlock
+                            }
+                        }
+                    ) -join [Environment]::NewLine * 2
                 }
             }
         }

GitHub/Jobs/BuildHelpOut.psd1

@@ -24,7 +24,11 @@
             if   = '${{github.ref_name != ''master''}}'
             uses = './'
             id = 'HelpOutBranch'
-        }      
-
+        },
+        @{
+            name = 'PSA'
+            uses = 'StartAutomating/PSA@main'
+            id = 'PSA'
+        }
     )
 }

HelpOut-Help.xml

@@ -8,7 +8,7 @@
       <maml:description>
         <maml:para>Gets MAML help</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Gets Markdown Help</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Gets a script's references</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</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>
@@ -792,7 +792,7 @@ If not provided, this will be the order they are defined in the formatter.</maml
       <maml:description>
         <maml:para>Gets a Script's story</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Installs MAML into a module</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Determines the percentage of documentation</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Saves a Module's MAML</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</dev:version>
     </command:details>
     <maml:description>
       <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
       <maml:description>
         <maml:para>Saves a Module's Markdown Help</maml:para>
       </maml:description>
-      <dev:version>0.4.7</dev:version>
+      <dev:version>0.4.8</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>

HelpOut.GitHubWorkflow.PSDevOps.ps1

@@ -10,7 +10,10 @@ Import-BuildStep -Module HelpOut
 New-GitHubWorkflow -Name "Test, Tag, Release, and Publish" -On Demand, Push -Job PowerShellStaticAnalysis, 
     TestPowerShellOnLinux, 
     TagReleaseAndPublish, 
-    BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml
+    BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml -Env @{        
+        "AT_PROTOCOL_HANDLE" = "mrpowershell.bsky.social"
+        "AT_PROTOCOL_APP_PASSWORD" = '${{ secrets.AT_PROTOCOL_APP_PASSWORD }}'
+    }
 
 New-GitHubWorkflow -On Demand, 
     Released -Job RunGitPub -Name OnIssueOrRelease -OutputPath .\.github\workflows\GitPub.yml

HelpOut.PSA.ps1

@@ -0,0 +1,47 @@
+# Any *.PSA.ps1 file will be run when PSA runs.
+
+# A good thing to do at the start of this file is to connect.
+
+Connect-BlueSky
+
+# If $env:AT_PROTOCOL_HANDLE or $env:AT_PROTOCOL_EMAIL is set, it will be treated as the username
+# If $env:AT_PROTOCOL_APP_PASSWORD is set, it will be treated as the App Password.
+# _Never_ use your actual BlueSky password
+
+# Once we're connected, we can do anything our app password allows.
+
+# However, you _might_ want to output some information first, so that you can see you're connected.
+
+Get-BskyActorProfile -Actor $env:AT_PROTOCOL_HANDLE -Cache | Out-Host
+
+# To ensure you're not going to send a skeet on every checkin, it's a good idea to ask what GitHub is up to
+
+# There will be a variable, $GitHubEvent, that contains information about the event.
+
+# A fairly common scenario is to perform an annoucement whenever a PR is merged.
+
+$isMergeToMain = 
+    ($gitHubEvent.head_commit.message -match "Merge Pull Request #(?<PRNumber>\d+)") -and 
+    $gitHubEvent.ref -eq 'refs/heads/main'
+
+if ($isMergeToMain) {
+    Import-Module .\HelpOut.psd1 -Global -PassThru | Out-Host
+    $helpOutModule = Get-Module HelpOut
+    $moduleAndVersion = "$($helpOutModule.Name) $($helpOutModule.Version)"
+    $fullMessage = @(
+        "#PowerShell just got a little more helpful: ",
+        "Auto-generating #PowerShell docs gets easier every release: ",
+        "#PowerShell people, help yourself to new bits: " |
+            Get-Random        
+
+        "$moduleAndVersion is out!"
+    )    
+
+    Send-AtProto -Text $fullMessage -WebCard @{
+        Url = "https://github.com/StartAutomating/HelpOut"
+    } -LinkPattern @{
+        "HelpOut" = "https://github.com/StartAutomating/HelpOut"
+    }
+
+    return
+}