Skip to content

Commit

Permalink
Merge pull request #44 from StartAutomating/HelpingOutWithMinorImprov…
Browse files Browse the repository at this point in the history 
…ements

HelpingOutWithMinorImprovements
  • Loading branch information
@StartAutomating
StartAutomating authored Jun 21, 2022
2 parents f2d5815 + f6b9cdc commit 4da9b08
Show file tree
Hide file tree
Showing 3 changed files with 128 additions and 59 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,11 @@
### 0.2.6
* Save-MarkdownHelp:
* Improving Inline Documentation
* Allowing -ScriptPath to be a Regex (#41)
* Fixing Relative Paths with -IncludeExtension (#42)
* Improving -IncludeTopic regex behavior (#43)
---

### 0.2.5
* Save-MarkdownHelp:
* Adding -IncludeExtension (#35)
Expand Down
9 changes: 8 additions & 1 deletion HelpOut.psd1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,21 @@
Author='James Brundage'
ModuleToProcess='HelpOut.psm1'
FormatsToProcess='HelpOut.format.ps1xml'
ModuleVersion='0.2.5'
ModuleVersion='0.2.6'
PrivateData = @{
PSData = @{
ProjectURI = 'https://github.com/StartAutomating/HelpOut'
LicenseURI = 'https://github.com/StartAutomating/HelpOut/blob/master/LICENSE'

Tags = 'Markdown', 'Help','PowerShell'
ReleaseNotes = @'
### 0.2.6
* Save-MarkdownHelp:
* Improving Inline Documentation
* Allowing -ScriptPath to be a Regex (#41)
* Fixing Relative Paths with -IncludeExtension (#42)
* Improving -IncludeTopic regex behavior (#43)
---
### 0.2.5
* Save-MarkdownHelp:
* Adding -IncludeExtension (#35)
Expand Down
170 changes: 112 additions & 58 deletions Save-MarkdownHelp.ps1
View file
Original file line number Diff line number Diff line change
Expand Up @@ -109,118 +109,172 @@ function Save-MarkdownHelp

$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) {
$theModuleRoot = $theModule | Split-Path # Find the module's root.
if (-not $psBoundParameters.OutputPath) { # If no -OutputPath was provided
$OutputPath =
if ($Wiki) {
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"
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
$null = New-Item -ItemType Directory -Path $OutputPath # create it.
}

# Double-check that the output path
$outputPathItem = Get-Item $OutputPath
if ($outputPathItem -isnot [IO.DirectoryInfo]) {
if ($outputPathItem -isnot [IO.DirectoryInfo]) { # is not a directory
# (if it is, error out).
Write-Error "-OutputPath '$outputPath' must point to a directory"
return
}

$myHelpParams = @{}
if ($wiki) { $myHelpParams.Wiki = $true}
else { $myHelpParams.GitHubDocRoot = $OutputPath | Split-Path}


# Next we're going to call Get-MarkdownHelp on each exported command.
foreach ($cmd in $theModule.ExportedCommands.Values) {
$docOutputPath = Join-Path $outputPath ($cmd.Name + '.md')
# 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) { $getMarkdownHelpSplat.Wiki = $Wiki}

# 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| Out-String -Width 1mb | Set-Content -Path $docOutputPath -Encoding utf8
if ($PassThru) {

& $GetMarkdownHelp @getMarkdownHelpSplat | # Call Get-MarkdownHelp
Out-String -Width 1mb | # output it as a string
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 a -ScriptPath was provided
if ($ScriptPath) {
$childitems = Get-ChildItem -Path $theModuleRoot -Recurse
foreach ($sp in $ScriptPath) {
$childitems |
Where-Object {
$_.Name -eq $sp -or $_.FullName -eq $sp -or $_.Name -like $sp -or $_.FullName -like $sp
} |
Get-ChildItem |
Where-Object Extension -eq '.ps1' |
ForEach-Object {
$ps1File = $_
$getMarkdownHelpSplat = @{Name="$($ps1File.FullName)"} + $getMarkdownHelpSplatBase
$replacedFileName = $ps1File.Name
@(for ($ri = 0; $ri -lt $ReplaceScriptName.Length; $ri++) {
if ($ReplaceScriptNameWith[$ri]) {
$replacedFileName = $replacedFileName -replace $ReplaceScriptName[$ri], $ReplaceScriptNameWith[$ri]
} else {
$replacedFileName = $replacedFileName -replace $ReplaceScriptName[$ri]
}
})
$docOutputPath = Join-Path $outputPath ($replacedFileName + '.md')
$relativePath = $ps1File.FullName.Substring("$theModuleRoot".Length).TrimStart('/\').Replace('\','/')
$getMarkdownHelpSplat.Rename = $relativePath
if ($Wiki) { $getMarkdownHelpSplat.Wiki = $Wiki}
else { $getMarkdownHelpSplat.GitHubDocRoot = "$($outputPath|Split-Path -Leaf)"}
& $GetMarkdownHelp @getMarkdownHelpSplat| Out-String -Width 1mb | Set-Content -Path $docOutputPath -Encoding utf8
if ($PassThru) {
Get-Item -Path $docOutputPath -ErrorAction SilentlyContinue
# 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[$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.

if ($PassThru) { # If -PassThru was provided
Get-Item -Path $docOutputPath -ErrorAction SilentlyContinue # return the created file.
}


}
}
}

# If -IncludeTopic was provided
if ($IncludeTopic) {
# get all of the children beneath the module root
Get-ChildItem -Path $theModuleRoot -Recurse -File |
ForEach-Object {
$fileInfo = $_
foreach ($inc in $IncludeTopic) {
foreach ($inc in $IncludeTopic) { # find any files that should be included
$matches = $null
if ($fileInfo.Name -eq $inc -or $fileInfo.Name -like $inc -or
(-not $inc.Contains('*') -and $(try {$fileInfo.Name -match $inc} catch {$null}))
if ($fileInfo.Name -eq $inc -or
$fileInfo.Name -like $inc -or
$(
$incRegex = $inc -as [regex]
$incRegex -and $fileInfo.Name -match $incRegex
)
) {
$replacedName =
if ($matches) {
$fileInfo.Name -replace $inc
if ($matches) { # If $inc was a regex
$fileInfo.Name -replace $inc # just replace it
} else {
$fileInfo.Name.Substring(0, $fileInfo.name.Length - $fileInfo.Extension.Length) -replace '\.help$'
# 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") {
$replacedName = 'README'
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')
if ($fileInfo.FullName -ne "$dest") {
$fileInfo | Copy-Item -Destination $dest -PassThru:$PassThru
# and make sure we're not overwriting ourselves
if ($fileInfo.FullName -ne "$dest") {
$fileInfo | Copy-Item -Destination $dest -PassThru:$PassThru # then copy the file.
}
}
}
}
}


# 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) {
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
$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.
$fileInfo | Copy-Item -Destination $dest -PassThru:$PassThru
}
break
Expand Down

0 comments on commit 4da9b08

Please sign in to comment.