Skip to content

Commit 75e579f

Browse files
StartAutomatingStartAutomating
authored
Merge pull request #170 from StartAutomating/Helping-Out
HelpOut 0.5.2
2 parents 40c3dfa + 3effb08 commit 75e579f

9 files changed

Lines changed: 324 additions & 23 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,16 @@
1+
### HelpOut 0.5.2:
2+
3+
* Save-MarkdownHelp:
4+
* IncludeSubModule/-ExcludeSubModule ( #155 )
5+
* -IncludePath ( #169 )
6+
* -ExcludeFile aliases ( #168 )
7+
* -ExcludeExtension ( #167 )
8+
* Not Saving Files with colons ( #163 )
9+
10+
Thanks @PrzemyslawKlys !
11+
12+
---
13+
114
### HelpOut 0.5.1:
215

316
* Save-MarkdownHelp - -OutputPath now handles relative paths (#159)

‎HelpOut-Help.xml‎

Lines changed: 118 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.1</dev:version>
11+
<dev:version>0.5.2</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.5.1</dev:version>
403+
<dev:version>0.5.2</dev:version>
404404
</command:details>
405405
<maml:description>
406406
<maml:para>Gets Help for a given command, in Markdown</maml:para>
@@ -703,7 +703,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
703703
<maml:description>
704704
<maml:para>Gets a script's references</maml:para>
705705
</maml:description>
706-
<dev:version>0.5.1</dev:version>
706+
<dev:version>0.5.2</dev:version>
707707
</command:details>
708708
<maml:description>
709709
<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>
@@ -829,7 +829,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
829829
<maml:description>
830830
<maml:para>Gets a Script's story</maml:para>
831831
</maml:description>
832-
<dev:version>0.5.1</dev:version>
832+
<dev:version>0.5.2</dev:version>
833833
</command:details>
834834
<maml:description>
835835
<maml:para>Gets the Script's "Story"</maml:para>
@@ -992,7 +992,7 @@ Get-MarkdownHelp Get-Help # Get-MarkdownHelp is a wrapper for Get-Help </dev:cod
992992
<maml:description>
993993
<maml:para>Installs MAML into a module</maml:para>
994994
</maml:description>
995-
<dev:version>0.5.1</dev:version>
995+
<dev:version>0.5.2</dev:version>
996996
</command:details>
997997
<maml:description>
998998
<maml:para>Installs MAML into a module. </maml:para>
@@ -1428,7 +1428,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
14281428
<maml:description>
14291429
<maml:para>Determines the percentage of documentation</maml:para>
14301430
</maml:description>
1431-
<dev:version>0.5.1</dev:version>
1431+
<dev:version>0.5.2</dev:version>
14321432
</command:details>
14331433
<maml:description>
14341434
<maml:para>Determines the percentage of documentation in a given script</maml:para>
@@ -1571,7 +1571,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
15711571
<maml:description>
15721572
<maml:para>Saves a Module's MAML</maml:para>
15731573
</maml:description>
1574-
<dev:version>0.5.1</dev:version>
1574+
<dev:version>0.5.2</dev:version>
15751575
</command:details>
15761576
<maml:description>
15771577
<maml:para>Generates a Module's MAML file, and then saves it to the appropriate location.</maml:para>
@@ -1832,7 +1832,7 @@ This slightly reduces the size of the MAML file, and reduces the rate of changes
18321832
<maml:description>
18331833
<maml:para>Saves a Module's Markdown Help</maml:para>
18341834
</maml:description>
1835-
<dev:version>0.5.1</dev:version>
1835+
<dev:version>0.5.2</dev:version>
18361836
</command:details>
18371837
<maml:description>
18381838
<maml:para>Get markdown help for each command in a module and saves it to the appropriate location.</maml:para>
@@ -2058,6 +2058,20 @@ If the file name starts and ends with slashes, it will be treated as a Regular E
20582058
<dev:defaultValue>
20592059
</dev:defaultValue>
20602060
</command:parameter>
2061+
<command:parameter required="false" position="named" pipelineInput="True (ByPropertyName)" aliases="" variableLength="true" globbing="false">
2062+
<maml:name>IncludeFile</maml:name>
2063+
<maml:description>
2064+
<maml:para>A whitelist of files or directories to include.
2065+
If this is provided, only files that match these criteria will be included.</maml:para>
2066+
</maml:description>
2067+
<command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
2068+
<dev:type>
2069+
<maml:name>System.String[]</maml:name>
2070+
<maml:uri />
2071+
</dev:type>
2072+
<dev:defaultValue>
2073+
</dev:defaultValue>
2074+
</command:parameter>
20612075
<command:parameter required="false" position="named" pipelineInput="True (ByPropertyName)" aliases="" variableLength="true" globbing="false">
20622076
<maml:name>IncludeExtension</maml:name>
20632077
<maml:description>
@@ -2072,6 +2086,47 @@ By default, .css, .gif, .htm, .html, .js, .jpg, .jpeg, .mp4, .png, .svg</maml:pa
20722086
<dev:defaultValue>
20732087
</dev:defaultValue>
20742088
</command:parameter>
2089+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2090+
<maml:name>ExcludeExtension</maml:name>
2091+
<maml:description>
2092+
<maml:para>One or more extensions to exclude.
2093+
By default, not extensions are specifically excluded.</maml:para>
2094+
</maml:description>
2095+
<command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
2096+
<dev:type>
2097+
<maml:name>System.String[]</maml:name>
2098+
<maml:uri />
2099+
</dev:type>
2100+
<dev:defaultValue>
2101+
</dev:defaultValue>
2102+
</command:parameter>
2103+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2104+
<maml:name>IncludeSubmodule</maml:name>
2105+
<maml:description>
2106+
<maml:para>If set, will explicitly include submodule directories.</maml:para>
2107+
</maml:description>
2108+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2109+
<dev:type>
2110+
<maml:name>Switch</maml:name>
2111+
<maml:uri />
2112+
</dev:type>
2113+
<dev:defaultValue>
2114+
</dev:defaultValue>
2115+
</command:parameter>
2116+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2117+
<maml:name>ExcludeSubModule</maml:name>
2118+
<maml:description>
2119+
<maml:para>If set, will explicitly exclude submodule directories.
2120+
This is the default.</maml:para>
2121+
</maml:description>
2122+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2123+
<dev:type>
2124+
<maml:name>Switch</maml:name>
2125+
<maml:uri />
2126+
</dev:type>
2127+
<dev:defaultValue>
2128+
</dev:defaultValue>
2129+
</command:parameter>
20752130
<command:parameter required="false" position="named" pipelineInput="True (ByPropertyName)" aliases="" variableLength="true" globbing="false">
20762131
<maml:name>NoValidValueEnumeration</maml:name>
20772132
<maml:description>
@@ -2159,6 +2214,20 @@ In either context, `$_` will be the current attribute.</maml:para>
21592214
<dev:defaultValue>
21602215
</dev:defaultValue>
21612216
</command:parameter>
2217+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2218+
<maml:name>ExcludeExtension</maml:name>
2219+
<maml:description>
2220+
<maml:para>One or more extensions to exclude.
2221+
By default, not extensions are specifically excluded.</maml:para>
2222+
</maml:description>
2223+
<command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
2224+
<dev:type>
2225+
<maml:name>System.String[]</maml:name>
2226+
<maml:uri />
2227+
</dev:type>
2228+
<dev:defaultValue>
2229+
</dev:defaultValue>
2230+
</command:parameter>
21622231
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
21632232
<maml:name>ExcludeFile</maml:name>
21642233
<maml:description>
@@ -2174,6 +2243,20 @@ If the file name starts and ends with slashes, it will be treated as a Regular E
21742243
<dev:defaultValue>
21752244
</dev:defaultValue>
21762245
</command:parameter>
2246+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2247+
<maml:name>ExcludeSubModule</maml:name>
2248+
<maml:description>
2249+
<maml:para>If set, will explicitly exclude submodule directories.
2250+
This is the default.</maml:para>
2251+
</maml:description>
2252+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2253+
<dev:type>
2254+
<maml:name>Switch</maml:name>
2255+
<maml:uri />
2256+
</dev:type>
2257+
<dev:defaultValue>
2258+
</dev:defaultValue>
2259+
</command:parameter>
21772260
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
21782261
<maml:name>ExcludeTopic</maml:name>
21792262
<maml:description>
@@ -2220,6 +2303,33 @@ By default, .css, .gif, .htm, .html, .js, .jpg, .jpeg, .mp4, .png, .svg</maml:pa
22202303
<dev:defaultValue>
22212304
</dev:defaultValue>
22222305
</command:parameter>
2306+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2307+
<maml:name>IncludeFile</maml:name>
2308+
<maml:description>
2309+
<maml:para>A whitelist of files or directories to include.
2310+
If this is provided, only files that match these criteria will be included.</maml:para>
2311+
</maml:description>
2312+
<command:parameterValue required="false" variableLength="true">System.String[]</command:parameterValue>
2313+
<dev:type>
2314+
<maml:name>System.String[]</maml:name>
2315+
<maml:uri />
2316+
</dev:type>
2317+
<dev:defaultValue>
2318+
</dev:defaultValue>
2319+
</command:parameter>
2320+
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
2321+
<maml:name>IncludeSubmodule</maml:name>
2322+
<maml:description>
2323+
<maml:para>If set, will explicitly include submodule directories.</maml:para>
2324+
</maml:description>
2325+
<command:parameterValue required="false" variableLength="true">Switch</command:parameterValue>
2326+
<dev:type>
2327+
<maml:name>Switch</maml:name>
2328+
<maml:uri />
2329+
</dev:type>
2330+
<dev:defaultValue>
2331+
</dev:defaultValue>
2332+
</command:parameter>
22232333
<command:parameter required="false" position="named" pipelineInput="False" aliases="" variableLength="true" globbing="false">
22242334
<maml:name>IncludeTopic</maml:name>
22252335
<maml:description>

‎HelpOut.psd1‎

Lines changed: 11 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,35 @@
11
@{
2-
Copyright='2019-2023 Start-Automating'
2+
Copyright='2019-2024 Start-Automating'
33
Description='A Helpful Toolkit for Managing PowerShell Help'
44
CompanyName='Start-Automating'
55
Guid='3f57070a-240f-4406-8e8e-6351ffe6f85b'
66
Author='James Brundage'
77
ModuleToProcess='HelpOut.psm1'
88
FormatsToProcess='HelpOut.format.ps1xml'
99
TypesToProcess='HelpOut.types.ps1xml'
10-
ModuleVersion='0.5.1'
10+
ModuleVersion='0.5.2'
1111
PrivateData = @{
1212
PSData = @{
1313
ProjectURI = 'https://github.com/StartAutomating/HelpOut'
1414
LicenseURI = 'https://github.com/StartAutomating/HelpOut/blob/master/LICENSE'
1515

1616
Tags = 'Markdown', 'Help','PowerShell'
1717
ReleaseNotes = @'
18-
### HelpOut 0.5.1:
18+
### HelpOut 0.5.2:
1919
20-
* Save-MarkdownHelp - -OutputPath now handles relative paths (#159)
21-
* Markdown Help Formatting - Trimming Whitespace (#161) (rendering should be unchanged)
20+
* Save-MarkdownHelp:
21+
* IncludeSubModule/-ExcludeSubModule ( #155 )
22+
* -IncludePath ( #169 )
23+
* -ExcludeFile aliases ( #168 )
24+
* -ExcludeExtension ( #167 )
25+
* Not Saving Files with colons ( #163 )
2226
23-
Thanks @PrzemyslawKlys !
27+
Thanks @PrzemyslawKlys !
2428
2529
---
2630
2731
Additional Changes in [Changelog](/CHANGELOG.md)
28-
Like It? Start It. Love It? Support It.
32+
Like It? Star It. Love It? Support It.
2933
3034
'@
3135
}

‎HelpOut.types.ps1xml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ $FilePath,
6161
$View = 'PowerShell.Markdown.Help'
6262
)
6363

64-
if ($filePath -match '[\&lt;\&gt;\|\?\*]') {
64+
if ($filePath -match '[\&lt;\&gt;\|\?\*\:]') {
6565
Write-Warning "Will not .Save to $filePath, because that path will not be readable on all operating systems."
6666
return
6767
}

‎Save-MarkdownHelp.ps1‎

Lines changed: 66 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -100,15 +100,37 @@
100100
# By default, this is treated as a wildcard.
101101
# If the file name starts and ends with slashes, it will be treated as a Regular Expression.
102102
[Parameter(ValueFromPipelineByPropertyName)]
103+
[Alias('ExcludePath','ExcludeDirectory','ExcludeFolder')]
103104
[string[]]
104105
$ExcludeFile,
105106

107+
# A whitelist of files or directories to include.
108+
# If this is provided, only files that match these criteria will be included.
109+
[Parameter(ValueFromPipelineByPropertyName)]
110+
[Alias('IncludePath','IncludeDirectory','IncludeFolder')]
111+
[string[]]
112+
$IncludeFile,
113+
106114
# One or more extensions to include.
107115
# By default, .css, .gif, .htm, .html, .js, .jpg, .jpeg, .mp4, .png, .svg
108116
[Parameter(ValueFromPipelineByPropertyName)]
109117
[string[]]
110118
$IncludeExtension = @('.css','.gif', '.htm', '.html','.js', '.jpg', '.jpeg', '.mp4', '.png', '.svg'),
111119

120+
# One or more extensions to exclude.
121+
# By default, not extensions are specifically excluded.
122+
[string[]]
123+
$ExcludeExtension,
124+
125+
# If set, will explicitly include submodule directories.
126+
[switch]
127+
$IncludeSubmodule,
128+
129+
# If set, will explicitly exclude submodule directories.
130+
# This is the default.
131+
[switch]
132+
$ExcludeSubModule,
133+
112134
# If set, will not enumerate valid values and enums of parameters.
113135
[Parameter(ValueFromPipelineByPropertyName)]
114136
[switch]
@@ -153,6 +175,23 @@
153175
}
154176

155177
$NotExcluded = {
178+
if ($IncludeFile) {
179+
$shouldIncludePath =
180+
foreach ($include in $IncludeFile) {
181+
if ($include -match '^/' -and $include -match '/$') {
182+
if ([Regex]::New(
183+
$include -replace '^/' -replace '/$', 'IgnoreCase,IgnorePatternWhitespace'
184+
).Match($_.FullName)) {
185+
$true;break
186+
}
187+
} else {
188+
if ($_.FullName -like $include -or $_.Name -like $include) {
189+
$true;break
190+
}
191+
}
192+
}
193+
if (-not $shouldIncludePath) { return $false }
194+
}
156195
if (-not $ExcludeFile) { return $true }
157196
foreach ($ex in $ExcludeFile) {
158197
if ($ex -match '^/' -and $ex -match '/$') {
@@ -183,7 +222,7 @@
183222
}
184223

185224
$c = 0
186-
$t = $Module.Count
225+
$t = $Module.Count
187226

188227
#region Save the Markdowns
189228
foreach ($m in $Module) { # Walk thru the list of module names.
@@ -213,6 +252,25 @@
213252
$null = New-Item -ItemType Directory -Path $OutputPath # create it.
214253
}
215254

255+
if ((-not $ExcludeSubModule) -and (-not $IncludeSubmodule)) {
256+
Push-Location $theModuleRoot
257+
258+
$gitCmd = $ExecutionContext.SessionState.InvokeCommand.GetCommand('git','Alias,Application')
259+
$submoduleRoots =
260+
if ($gitCmd -is [Management.Automation.AliasInfo]) {
261+
git submodule | Select-Object -ExpandProperty Submodule
262+
}
263+
else {
264+
git submodule | & { process {@($_ -split '\s')[1]} }
265+
}
266+
267+
if ($submoduleRoots) {
268+
$ExcludeFile += "$($pwd)$([io.path]::DirectorySeparatorChar)$submoduleRoot$([io.path]::DirectorySeparatorChar)*"
269+
}
270+
271+
Pop-Location
272+
}
273+
216274
$outputPathName = $OutputPath | Split-Path -Leaf
217275
$ReplaceLink += "^$outputPathName[\\/]"
218276

@@ -449,6 +507,13 @@
449507
Where-Object $NotExcluded | # (and as long as they're not excluded)
450508
ForEach-Object {
451509
$fileInfo = $_
510+
if ($ExcludeExtension) {
511+
foreach ($ext in $ExcludeExtension) {
512+
if ($fileInfo.Extension -eq $ext -or $fileInfo.Extension -eq ".$ext") {
513+
return
514+
}
515+
}
516+
}
452517
foreach ($ext in $IncludeExtension) { # and see if they are the right extension
453518
if ($fileInfo.Extension -eq $ext -or $fileInfo.Extension -eq ".$ext") {
454519
# Determine the relative path

0 commit comments

Comments
 (0)