Save-MarkdownHelp.ps1

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
function Save-MarkdownHelp
{
    <#
    .Synopsis
        Saves a Module's Markdown Help
    .Description
        Get markdown help for each command in a module and saves it to the appropriate location.
    .Link
        Get-MarkdownHelp
    .Example
        Save-MarkdownHelp -Module HelpOut # Save Markdown to HelpOut/docs
    .Example
        Save-MarkdownHelp -Module HelpOut -Wiki # Save Markdown to ../HelpOut.wiki
    #>

    param(
    # The name of one or more modules.
    [Parameter(ParameterSetName='ByModule',ValueFromPipelineByPropertyName=$true)]
    [string[]]
    $Module,

    # The output path.
    # If not provided, will be assumed to be the "docs" folder of a given module (unless -Wiki is specified)
    [Parameter(ValueFromPipelineByPropertyName)]
    [string]
    $OutputPath,

    # If set, will interlink documentation as if it were a wiki. Implied when -OutputPath contains 'wiki'.
    # If provided without -OutputPath, will assume that a wiki resides in a sibling directory of the module.
    [Parameter(ValueFromPipelineByPropertyName)]
    [switch]
    $Wiki,

    # If provided, will generate documentation for additional commands.
    [Parameter(ValueFromPipelineByPropertyName)]
    [Management.Automation.CommandInfo[]]
    $Command,

    # Replaces parts of the names of the commands provided in the -Command parameter.
    # -ReplaceScriptName is treated as a regular expression.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceCommandName,

    # If provided, will replace parts of the names of the scripts discovered in a -Command parameter with a given Regex replacement.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceCommandNameWith = @(),

    # If provided, will generate documentation for any scripts found within these paths.
    # -ScriptPath can be either a file name or a full path.
    # If an exact match is not found -ScriptPath will also check to see if there is a wildcard match.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ScriptPath,

    # If provided, will replace parts of the names of the scripts discovered in a -ScriptDirectory beneath a module.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceScriptName,

    # If provided, will replace parts of the names of the scripts discovered in a -ScriptDirectory beneath a module with a given Regex replacement.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceScriptNameWith = @(),

    # If provided, will replace links discovered in markdown content.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceLink,

    # If provided, will replace links discovered in markdown content with a given Regex replacement.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ReplaceLinkWith = @(),

    # If set, will output changed or created files.
    [switch]
    $PassThru,

    # The order of the sections. If not provided, this will be the order they are defined in the formatter.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $SectionOrder,

    # One or more topic files to include.
    # Topic files will be treated as markdown and directly copied inline.
    # By default ```\.help\.txt$``` and ```\.md$```
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $IncludeTopic = @('\.help\.txt$', '\.md$'),

    # One or more topic file patterns to exclude.
    # Topic files that match this pattern will not be included.
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $ExcludeTopic = @('\.ps1{0,1}\.md$'),

    # One or more extensions to include.
    # By default, .css, .gif, .htm, .html, .js, .jpg, .jpeg, .mp4, .png, .svg
    [Parameter(ValueFromPipelineByPropertyName)]
    [string[]]
    $IncludeExtension = @('.css','.gif', '.htm', '.html','.js', '.jpg', '.jpeg', '.mp4', '.png', '.svg'),

    # If set, will not enumerate valid values and enums of parameters.
    [Parameter(ValueFromPipelineByPropertyName)]
    [switch]
    $NoValidValueEnumeration,

    # If set, will not attach a YAML header to the generated help.
    [Parameter(ValueFromPipelineByPropertyName)]
    [Alias('IncludeFrontMatter', 'IncludeHeader')]
    [switch]
    $IncludeYamlHeader,

    # The type of information to include in the YAML Header
    [ValidateSet('Command','Help','Metadata')]
    [Alias('YamlHeaderInfoType')]
    [string[]]
    $YamlHeaderInformationType,    

    # A list of command types to skip.
    # If not provided, all types of commands from the module will be saved as a markdown document.
    [Parameter(ValueFromPipelineByPropertyName)]
    [Alias('SkipCommandTypes','ExcludeCommandType','ExcludeCommandTypes')]
    [Management.Automation.CommandTypes[]]
    $SkipCommandType
    )

    begin {
        # First, let's cache a reference to Get-MarkdownHelp
        $GetMarkdownHelp = 
            if ($MyInvocation.MyCommand.ScriptBlock.Module) {
                $MyInvocation.MyCommand.ScriptBlock.Module.ExportedCommands['Get-MarkdownHelp']
            } else {
                $ExecutionContext.SessionState.InvokeCommand.GetCommand('Get-MarkdownHelp', 'Function')
            }

        $filesChanged = @()
    }

    process {        
        $getMarkdownHelpSplatBase = @{}

        foreach ($param in $psBoundParameters.Keys) {
            if ($GetMarkdownHelp.Parameters[$param]) {
                $getMarkdownHelpSplatBase[$param] = $psBoundParameters[$param]
            }
        }
        

        #region Save the Markdowns
        foreach ($m in $Module) { # Walk thru the list of module names.
            if ($t -gt 1) {
                $c++
                Write-Progress 'Saving Markdown' $m -PercentComplete $p  -Id $id
            }

            $theModule = Get-Module $m # Find the module
            if (-not $theModule) { continue } # (continue if we couldn't).
            $theModuleRoot = $theModule | Split-Path # Find the module's root.
            if (-not $psBoundParameters.OutputPath) { # If no -OutputPath was provided
                $OutputPath = 
                    if ($Wiki) { # set the default. If it's a wiki, it's a sibling directory
                        Split-Path $theModuleRoot | Join-Path -ChildPath "$($theModule.Name).wiki"
                    } else {
                        Join-Path $theModuleRoot "docs" # Otherwise, it's the docs subdirectory.
                    }                
            }
            
            # If the -OutputPath does not exist
            if (-not (Test-Path $OutputPath)) {
                $null = New-Item -ItemType Directory -Path $OutputPath # create it.
            }

            $outputPathName = $OutputPath | Split-Path -Leaf
            $ReplaceLink   += "^$outputPathName[\\/]"

            # Double-check that the output path
            $outputPathItem = Get-Item $OutputPath
            if ($outputPathItem -isnot [IO.DirectoryInfo]) { # is not a directory
                # (if it is, error out).
                Write-Error "-OutputPath '$outputPath' must point to a directory"
                return
            }
            
            # Next we're going to call Get-MarkdownHelp on each exported command.
            foreach ($cmd in $theModule.ExportedCommands.Values) {
                # If we specified command types to skip, skip them now.
                if ($SkipCommandType -and $SkipCommandType -contains $cmd.CommandType) {
                    continue
                }
                
                # Determine the output path for each item.
                $docOutputPath = Join-Path $outputPath ($cmd.Name + '.md')
                # 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)"}
                
                & $GetMarkdownHelp @getMarkdownHelpSplat | # Call Get-MarkdownHelp
                    Out-String -Width 1mb                | # output it as a string
                    ForEach-Object { $_.Trim()}          | # trim it
                    Set-Content -Path $docOutputPath -Encoding utf8  # and set the encoding.

                if ($PassThru) { # If -PassThru was provided, get the path.
                    Get-Item -Path $docOutputPath -ErrorAction SilentlyContinue
                }
            }

            if ($Command) {
                foreach ($cmd in $Command) {
                    # For each script that we find, prepare to call Get-MarkdownHelp
                    $getMarkdownHelpSplat = @{
                        Name= if ($cmd.Source) { "$($cmd.Source)" } else { "$cmd" }
                    } + $getMarkdownHelpSplatBase

                    $replacedCmdName = 
                        if ($cmd.DisplayName) {
                            $cmd.DisplayName
                        } elseif ($cmd.Name -and $cmd.Name.Contains([IO.Path]::DirectorySeparatorChar)) {
                            $cmd.Name
                        }

                    @(for ($ri = 0; $ri -lt $ReplaceCommandName.Length; $ri++) { # Walk over any -ReplaceScriptName(s) provided.
                        # Replace it with the -ReplaceScriptNameWith parameter (if present).
                        if ($ReplaceCommandNameWith -and $ReplaceCommandNameWith[$ri]) { 
                            $replacedCmdName = $replacedCmdName -replace $ReplaceCommandName[$ri], $ReplaceCommandNameWith[$ri]
                        } else {
                            # Otherwise, just remove the replacement.
                            $replacedCmdName = $replacedCmdName -replace $ReplaceCommandName[$ri]
                        }
                    })
                    
                    # Determine the output path for each item.
                    $docOutputPath = Join-Path $outputPath ($replacedCmdName + '.md')
                    $getMarkdownHelpSplat.Rename = $replacedCmdName
                    if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki}
                    else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"}
                    
                    try {           
                        & $GetMarkdownHelp @getMarkdownHelpSplat | # Call Get-MarkdownHelp
                            Out-String -Width 1mb                | # output it as a string
                            ForEach-Object { $_.Trim()}          | # trim it
                            Set-Content -Path $docOutputPath -Encoding utf8  # and set the encoding.
                    }
                    catch {
                        $ex = $_
                        Write-Error -Exception $ex.Exception -Message "Could not Get Help for $($cmd.Name): $($ex.Exception.Message)" -TargetObject $getMarkdownHelpSplat
                    }

                    $filesChanged += # add the file to the changed list.
                        Get-Item -Path $docOutputPath -ErrorAction SilentlyContinue 

                    # If -PassThru was provided (and we're not going to change anything)
                    if ($PassThru -and -not $ReplaceLink) { 
                        $filesChanged[-1] # output the file changed now.
                    }

                }
            }
            # If a -ScriptPath was provided
            if ($ScriptPath) {
                # get the child items beneath the module root.
                Get-ChildItem -Path $theModuleRoot -Recurse |                                    
                    Where-Object {
                        # Any Script Path whose Name or FullName is
                        foreach ($sp in $ScriptPath) {
                            $_.Name -eq $sp -or     # an exact match,
                            $_.FullName -eq $sp -or 
                            $_.Name -like $sp -or   # a wildcard match,
                            $_.FullName -like $sp -or $(
                                $spRegex = $sp -as [regex]
                                $spRegex -and (    # or a regex match
                                    $_.Name -match $spRegex -or
                                    $_.FullName -match $spRegex
                                )
                            )
                        }
                        # will be included.
                    } |
                    # Any child items of that path will also be included
                    Get-ChildItem -Recurse |
                    Where-Object Extension -eq '.ps1' | # (as long as they're PowerShell Scripts).
                    ForEach-Object {
                        $ps1File = $_
                        # For each script that we find, prepare to call Get-MarkdownHelp
                        $getMarkdownHelpSplat = @{Name="$($ps1File.FullName)"} + $getMarkdownHelpSplatBase
                        # because not all file names will be valid (or good) topic names
                        $replacedFileName = $ps1File.Name # prepare to replace the file.
                        @(for ($ri = 0; $ri -lt $ReplaceScriptName.Length; $ri++) { # Walk over any -ReplaceScriptName(s) provided.
                            if ($ReplaceScriptNameWith -and $ReplaceScriptNameWith[$ri]) { 
                                # Replace it with the -ReplaceScriptNameWith parameter (if present).
                                $replacedFileName = $replacedFileName -replace $ReplaceScriptName[$ri], $ReplaceScriptNameWith[$ri]
                            } else {
                                # Otherwise, just remove the replacement.
                                $replacedFileName = $replacedFileName -replace $ReplaceScriptName[$ri]
                            }
                        })
                        # Determine the output path
                        $docOutputPath = Join-Path $outputPath ($replacedFileName + '.md')
                        # and the relative path of this .ps1 to the module root.
                        $relativePath = $ps1File.FullName.Substring("$theModuleRoot".Length).TrimStart('/\').Replace('\','/')
                        # Then, rename the potential topic with it's relative path.
                        $getMarkdownHelpSplat.Rename = $relativePath
                        if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki}
                        else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"}
                        # Call Get-MarkdownHelp
                        & $GetMarkdownHelp @getMarkdownHelpSplat |
                            Out-String -Width 1mb | # format the result
                            Set-Content -Path $docOutputPath -Encoding utf8 # and save it to a file.
                        
                        
                        $filesChanged += # add the file to the changed list.
                            Get-Item -Path $docOutputPath -ErrorAction SilentlyContinue 
    
                        # If -PassThru was provided (and we're not going to change anything)
                        if ($PassThru -and -not $ReplaceLink) { 
                            $filesChanged[-1] # output the file changed now.
                        }
                    }                
            }

            # If -IncludeTopic was provided
            if ($IncludeTopic) {
                # get all of the children beneath the module root
                $filesArray = @(Get-ChildItem -Path $theModuleRoot -Recurse -File)
                # then reverse that list, so that the most shallow items come last.
                [array]::reverse($filesArray)
                $filesArray |
                    ForEach-Object {
                        $fileInfo = $_
                        # Determine the relative path of the file.
                        $relativePath  =
                            $fileInfo.FullName.Substring("$theModuleRoot".Length) -replace '^[\\/]'
                        # If it is more than one layer deep, ignore it.
                        if ([Regex]::Matches($relativePath, "[\\/]").Count -gt 1) {
                            return
                        }
                        :NextTopicFile foreach ($inc in $IncludeTopic) { # find any files that should be included
                            $matches = $null
                            if ($fileInfo.Name -eq $inc -or 
                                $fileInfo.Name -like $inc -or 
                                $(
                                    $incRegex = $inc -as [regex]
                                    $incRegex -and $fileInfo.Name -match $incRegex
                                )
                            ) {
                                # Double-check that the file should not excluded.
                                foreach ($exclude in $ExcludeTopic) {
                                    if (
                                        $fileInfo.Name -eq $exclude -or 
                                        $fileInfo.Name -like $exclude -or
                                        $(
                                            $exclude -as [regex] -and 
                                            $fileInfo.Name -match $exclude
                                        )
                                    ) {
                                        continue NextTopicFile
                                    }
                                }
                                $replacedName = 
                                    if ($matches) { # If $inc was a regex
                                        $fileInfo.Name -replace $inc # just replace it
                                    } else {
                                        # Otherwise, strip the file of it's extension
                                        $fileInfo.Name.Substring(0, 
                                            $fileInfo.name.Length - $fileInfo.Extension.Length) -replace '\.help$' # (and .help).
                                    }
                                
                                if ($replacedName -eq "about_$module") { # If the replaced named was "about_$Module"
                                    $replacedName = 'README' # treat it as the README
                                }
                                # Determine the output path
                                $dest = Join-Path $OutputPath ($replacedName + '.md')
                                # and make sure we're not overwriting ourselves
                                if ($fileInfo.FullName -ne "$dest") {                                     
                                    $filesChanged += # copy the file and add it to the change list.
                                        $fileInfo | Copy-Item -Destination $dest -PassThru 
                                }

                                # If -PassThru was passed and we're not changing anything.
                                if ($PassThru -and -not $ReplaceLink) {
                                    $filesChanged[-1] # output the file now.
                                }
                            }
                        }
                    }
            }
            
            # If -IncludeExtension was provided
            if ($IncludeExtension) {
                # get all files beneath the root
                Get-ChildItem -Path $theModuleRoot -Recurse -File |
                    ForEach-Object {
                        $fileInfo = $_
                        foreach ($ext in $IncludeExtension) { # and see if they are the right extension
                            if ($fileInfo.Extension -eq $ext -or $fileInfo.Extension -eq ".$ext") {
                                # Determine the relative path
                                $relativePath   = $fileInfo.FullName.Substring("$theModuleRoot".Length) -replace '^[\\/]'
                                $outputPathLeaf = $outputPath | Split-Path -Leaf
                                # and use that to determine the destination of this file.
                                $dest = Join-Path $OutputPath $relativePath
                                if ($fileInfo.FullName -ne "$dest" -and 
                                    $relativePath -notlike "$outputPathLeaf$([IO.Path]::DirectorySeparatorChar)*") {
                                    # Create the file (so it creates the folder structure).
                                    $createdFile = New-Item -ItemType File -Path $dest -Force 
                                    if (-not $createdFile) { # If we could not, write and error and stop trying for this file.
                                        Write-Error "Unable to initialize file: '$dest'"
                                        break
                                    }
                                    # Copy the file to the destination.
                                    if ($fileInfo.FullName -ne "$dest") {                                     
                                        $filesChanged += # and add it to the change list.
                                            $fileInfo | Copy-Item -Destination $dest -PassThru:$PassThru
                                    }
    
                                    # If -PassThru was passed and we're not changing anything.
                                    if ($PassThru -and -not $ReplaceLink) {
                                        $filesChanged[-1] # output the file now.
                                    }                                    
                                }
                                break
                            }
                        }
                    }
            }
        }

        if ($PassThru -and $ReplaceLink) {
            $linkFinder = [Regex]::new("
            (?<IsImage>\!)? # If there is an exclamation point, then it is an image link
            \[ # Markdown links start with a bracket
            (?<Text>[^\]\r\n]+)
            \] # anything until the end bracket is the link text.
            \( # The link uri is within parenthesis
            (?<Uri>[^\)\r\n]+)
            \)
            "
, 'IgnoreCase,IgnorePatternWhitespace')
            foreach ($file in $filesChanged) {
                if ($file.Extension -notin '.md', '.markdown') {
                    $file
                    continue
                }
                $fileContent = Get-Content $file.FullName -Raw
                $fileContent = $linkFinder.Replace($fileContent, {
                    param($LinkMatch)                    
                    $linkReplacementNumber = 0

                    $linkUri  = $LinkMatch.Groups["Uri"].ToString()
                    $linkText = $linkMatch.Groups["Text"].ToString()
                    foreach ($linkToReplace in $ReplaceLink) {
                        $replacement = "$($ReplaceLinkWith[$linkReplacementNumber])"
                        $linkUri  = $linkUri  -replace $linkToReplace, $replacement
                        $linkText = $linkText -replace $linkToReplace, $replacement                        
                    }

                    if ($linkUri -match '\#.+$') {
                        $lowerCaseAnchor = ($matches.0).ToLower()
                        $linkUri = $linkUri -replace '\#.+$', $lowerCaseAnchor
                    }

                    if ($LinkMatch.Groups["IsImage"].Length) {
                        "![$linkText]($linkUri)"
                    } else {
                        "[$linkText]($linkUri)"
                    }                    
                })
                Set-Content $file.FullName -Encoding UTF8 -Value $fileContent
                
                if ($PassThru) {
                    Get-Item -LiteralPath $file.FullName
                }
            }
        }

        if ($t -gt 1) {
            Write-Progress 'Saving Markdown' 'Complete' -Completed -Id $id
        }
        #endregion Save the Markdowns
    }
}