Skip to content

Commit a75a0da

Browse files
StartAutomatingStartAutomating
authored
Merge pull request #145 from StartAutomating/HelpOut-Updates
HelpOut 0.4.8
2 parents 12c7342 + 71f9e86 commit a75a0da

31 files changed

Lines changed: 376 additions & 115 deletions

‎.github/workflows/TestReleaseAndPublish.yml‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -590,4 +590,9 @@ jobs:
590590
if: ${{github.ref_name != 'master'}}
591591
uses: ./
592592
id: HelpOutBranch
593-
593+
- name: PSA
594+
uses: StartAutomating/PSA@main
595+
id: PSA
596+
env:
597+
AT_PROTOCOL_APP_PASSWORD: ${{ secrets.AT_PROTOCOL_APP_PASSWORD }}
598+
AT_PROTOCOL_HANDLE: mrpowershell.bsky.social

‎Assets/HelpOut.svg‎

Lines changed: 1 addition & 0 deletions
Loading

‎CHANGELOG.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,20 @@
1+
### HelpOut 0.4.8:
2+
3+
* Markdown Help Improvements:
4+
* Fixing Long Examples (Fixes #141)
5+
* Allowing first comment lines in an example to be markdown (#143)
6+
* Also, switching numbered example headings to blockquotes
7+
* Save-MarkdownHelp updates:
8+
* Fixing Piping Behavior (#140)
9+
* Not Saving to illegal windows paths (#132)
10+
* Improving Extended Types Doc Generation
11+
* Now puts extended type documentation into subfolders (#135)
12+
* Also, generates a summary file for each type (#133)
13+
* Updating links to Microsoft modules (#142)
14+
* Integrating PSA into HelpOut (#144)
15+
16+
---
17+
118
### HelpOut 0.4.7:
219

320
* Get-MarkdownHelp: Automatically renaming help about aliases (Fixes #130)

‎Extensions/HelpOut.SaveMarkdownHelp.ExtendedTypes.ps1‎

Lines changed: 52 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -31,15 +31,16 @@ $extendedTypeNames =
3131

3232
# and be ready to replace most punctuation
3333
$replaceMostPunctuation = '[\p{P}-[\-\._]]'
34+
$punctuationNotDashOrUnderscore = '[\p{P}-[\-_]]'
3435
# go over each extended type
3536
foreach ($extendedType in $extendedTypeNames) {
3637
# 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-
38+
$actualTypeData = Get-TypeData -TypeName $extendedType
4139

40+
$memberFiles =
41+
@(foreach ($member in $actualTypeData.Members.Values) {
4242
foreach ($potentialProperty in 'Script','GetScriptBlock','SetScriptBlock') {
43+
# If the script looks like it does not have inline help, continue
4344
if ($member.$PotentialProperty -notlike '*<#*.synopsis*#>*') { continue }
4445
$markdownSplat = @{}
4546
# Create a temporary function to hold the help.
@@ -53,6 +54,7 @@ foreach ($extendedType in $extendedTypeNames) {
5354
elseif ($potentialProperty -eq 'Script') {
5455
''
5556
}
57+
$fullExtendedTypeInfo = "$($extendedType).$GetSetNothing$($member.Name)"
5658
$temporaryFunctionName = "$($extendedType).$GetSetNothing$($member.Name)" -replace $replaceMostPunctuation
5759
$markdownSplat.Rename = "$temporaryFunctionName()"
5860
$ExecutionContext.SessionState.PSVariable.Set("function:$($temporaryFunctionName)", $member.$PotentialProperty)
@@ -63,12 +65,57 @@ foreach ($extendedType in $extendedTypeNames) {
6365
continue
6466
}
6567
$markdownHelp.HideSection("Syntax")
68+
69+
$etsDocPath = Join-Path $outputPath "$(
70+
@($fullExtendedTypeInfo -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar
71+
).md"
72+
6673
# .Save it,
67-
$markdownHelp.Save((Join-Path $outputPath "$($temporaryFunctionName).md"))
74+
$markdownHelp.Save($etsDocPath)
6875
# and remove the temporary function (it would have gone out of scope anyways)
6976
$ExecutionContext.SessionState.PSVariable.Remove("function:$($temporaryFunctionName)")
7077
}
7178

7279

80+
})
81+
82+
$ExtendedTypeDocFile = Join-Path $outputPath "$(
83+
($extendedType -split $punctuationNotDashOrUnderscore) -join [IO.Path]::DirectorySeparatorChar
84+
)$([IO.Path]::DirectorySeparatorChar)README.md"
85+
86+
$getSetFile = '\.(?>get|set)_'
87+
$ExtendedTypeDocContent = @(
88+
"## $extendedType"
89+
[Environment]::NewLine
90+
91+
if ($actualTypeData.Members -and $actualTypeData.Members["README"].Value) {
92+
$actualTypeData.Members["README"].Value
93+
}
94+
95+
96+
$propertyMemberFiles = $memberFiles | Where-Object Name -Match $getSetFile
97+
if ($propertyMemberFiles) {
98+
"### Script Properties"
99+
[Environment]::NewLine
100+
foreach ($memberFile in $propertyMemberFiles | Sort-Object { $_.Name -replace $getSetFile}) {
101+
"* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
102+
}
103+
}
104+
$methodMemberFiles = $memberFiles | Where-Object Name -NotMatch $getSetFile
105+
if ($methodMemberFiles) {
106+
"### Script Methods"
107+
[Environment]::NewLine
108+
foreach ($memberFile in $methodMemberFiles) {
109+
"* [$(@($memberFile.Name -split '[\p{P}-[_]]')[-2])]($($memberFile.Name))"
110+
}
111+
}
112+
113+
) -join ([Environment]::NewLine)
114+
115+
$ExtendedTypeDocContent | Set-Content -Path $ExtendedTypeDocFile
116+
if ($?) {
117+
Get-Item -Path $ExtendedTypeDocFile
73118
}
119+
120+
$memberFiles
74121
}

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

Lines changed: 43 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@
3434
}
3535
elseif ($linkedCmd -and ($linkedCmd.Module -like 'microsoft.*' -or $linkedCmd.Source -like 'microsoft.*')) {
3636
$linkSrc = if ($linkedCmd.Module) { $linkedCmd.Module} else { $linkedCmd.Source }
37-
"https://docs.microsoft.com/powershell/module/$linkSrc/$linkedCmd"
37+
"https://learn.microsoft.com/powershell/module/$linkSrc/$linkedCmd"
3838
} elseif ($helpObject.WikiLink) {
3939
$nav.LinkText
4040
} elseif ($null -ne $helpObject.DocLink) {
@@ -54,17 +54,49 @@
5454
Examples = {
5555
if ($helpObject.Examples) {
5656
Format-Markdown -Heading "Examples" -headingsize 3
57-
57+
58+
5859
foreach ($example in $helpObject.Examples.Example) {
59-
Format-Markdown -Heading ($example.Title -replace '^[-\s]+' -replace '[-\s]+$') -HeadingSize 4
60-
61-
if ($example.Code) {
62-
$example.Code | Format-Markdown -CodeLanguage PowerShell
63-
}
64-
65-
if ($example.Remarks) {
66-
($example.Remarks | Out-String -Width 1mb).Trim()
67-
}
60+
61+
# Combine the code and remarks
62+
$exampleLines =
63+
@(
64+
$example.Code
65+
foreach ($remark in $example.Remarks.text) {
66+
if (-not $remark) { continue }
67+
$remark
68+
}
69+
) -join ([Environment]::NewLine) -split '(?>\r\n|\n)' # and split into lines
70+
71+
# Anything until the first non-comment line is a markdown predicate to the example
72+
$nonCommentLine = $false
73+
$markdownLines = @()
74+
75+
# Go thru each line in the example as part of a loop
76+
$codeBlock = @(foreach ($exampleLine in $exampleLines) {
77+
if ($exampleLine -match '^\#' -and -not $nonCommentLine) {
78+
$markdownLines += $exampleLine -replace '^\#' -replace '^\s+'
79+
} else {
80+
$nonCommentLine = $true
81+
$exampleLine
82+
}
83+
}) -join [Environment]::NewLine
84+
@(
85+
if ($markdownLines) {
86+
$markdownLines -join [Environment]::NewLine
87+
} else {
88+
Format-Markdown -BlockQuote -InputObject ($example.Title -replace '^[-\s]+' -replace '[-\s]+$')
89+
}
90+
91+
if ($codeBlock) {
92+
$codeBlockAsScriptBlock = try { [ScriptBlock]::Create($codeBlock) } catch { $false }
93+
if ($codeBlockAsScriptBlock) {
94+
$codeBlockAsScriptBlock | Format-Markdown
95+
} else {
96+
$codeBlock
97+
}
98+
}
99+
) -join [Environment]::NewLine * 2
68100
}
69101
}
70102
}

‎GitHub/Jobs/BuildHelpOut.psd1‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,11 @@
2424
if = '${{github.ref_name != ''master''}}'
2525
uses = './'
2626
id = 'HelpOutBranch'
27-
}
28-
27+
},
28+
@{
29+
name = 'PSA'
30+
uses = 'StartAutomating/PSA@main'
31+
id = 'PSA'
32+
}
2933
)
3034
}

‎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.7</dev:version>
11+
<dev:version>0.4.8</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.7</dev:version>
403+
<dev:version>0.4.8</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.7</dev:version>
669+
<dev:version>0.4.8</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.7</dev:version>
795+
<dev:version>0.4.8</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.7</dev:version>
958+
<dev:version>0.4.8</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.7</dev:version>
1312+
<dev:version>0.4.8</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.7</dev:version>
1455+
<dev:version>0.4.8</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.7</dev:version>
1716+
<dev:version>0.4.8</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.GitHubWorkflow.PSDevOps.ps1‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,10 @@ Import-BuildStep -Module HelpOut
1010
New-GitHubWorkflow -Name "Test, Tag, Release, and Publish" -On Demand, Push -Job PowerShellStaticAnalysis,
1111
TestPowerShellOnLinux,
1212
TagReleaseAndPublish,
13-
BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml
13+
BuildHelpOut -OutputPath .\.github\workflows\TestReleaseAndPublish.yml -Env @{
14+
"AT_PROTOCOL_HANDLE" = "mrpowershell.bsky.social"
15+
"AT_PROTOCOL_APP_PASSWORD" = '${{ secrets.AT_PROTOCOL_APP_PASSWORD }}'
16+
}
1417

1518
New-GitHubWorkflow -On Demand,
1619
Released -Job RunGitPub -Name OnIssueOrRelease -OutputPath .\.github\workflows\GitPub.yml

‎HelpOut.PSA.ps1‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Any *.PSA.ps1 file will be run when PSA runs.
2+
3+
# A good thing to do at the start of this file is to connect.
4+
5+
Connect-BlueSky
6+
7+
# If $env:AT_PROTOCOL_HANDLE or $env:AT_PROTOCOL_EMAIL is set, it will be treated as the username
8+
# If $env:AT_PROTOCOL_APP_PASSWORD is set, it will be treated as the App Password.
9+
# _Never_ use your actual BlueSky password
10+
11+
# Once we're connected, we can do anything our app password allows.
12+
13+
# However, you _might_ want to output some information first, so that you can see you're connected.
14+
15+
Get-BskyActorProfile -Actor $env:AT_PROTOCOL_HANDLE -Cache | Out-Host
16+
17+
# 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
18+
19+
# There will be a variable, $GitHubEvent, that contains information about the event.
20+
21+
# A fairly common scenario is to perform an annoucement whenever a PR is merged.
22+
23+
$isMergeToMain =
24+
($gitHubEvent.head_commit.message -match "Merge Pull Request #(?<PRNumber>\d+)") -and
25+
$gitHubEvent.ref -eq 'refs/heads/main'
26+
27+
if ($isMergeToMain) {
28+
Import-Module .\HelpOut.psd1 -Global -PassThru | Out-Host
29+
$helpOutModule = Get-Module HelpOut
30+
$moduleAndVersion = "$($helpOutModule.Name) $($helpOutModule.Version)"
31+
$fullMessage = @(
32+
"#PowerShell just got a little more helpful: ",
33+
"Auto-generating #PowerShell docs gets easier every release: ",
34+
"#PowerShell people, help yourself to new bits: " |
35+
Get-Random
36+
37+
"$moduleAndVersion is out!"
38+
)
39+
40+
Send-AtProto -Text $fullMessage -WebCard @{
41+
Url = "https://github.com/StartAutomating/HelpOut"
42+
} -LinkPattern @{
43+
"HelpOut" = "https://github.com/StartAutomating/HelpOut"
44+
}
45+
46+
return
47+
}

0 commit comments

Comments
 (0)