-
Notifications
You must be signed in to change notification settings - Fork 10
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Handles dashes in documentation in repository Wiki (#159)
- Loading branch information
Showing
15 changed files
with
726 additions
and
16 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| <# | ||
| .SYNOPSIS | ||
| Converts a name to a format suitable for use as a Wiki sidebar link. | ||
| .DESCRIPTION | ||
| The ConvertTo-WikiSidebarLinkName function takes a string input and converts | ||
| it to a format that is suitable for use as a link name in a Wiki sidebar. It | ||
| replaces hyphens with spaces and converts Unicode hyphens to standard hyphens. | ||
| .PARAMETER Name | ||
| The string to be converted. This parameter is mandatory and can be passed via | ||
| the pipeline. | ||
| .EXAMPLE | ||
| PS C:\> ConvertTo-WikiSidebarLinkName -Name "My-Page-Name" | ||
| Returns: "My Page Name" | ||
| .EXAMPLE | ||
| PS C:\> ('Unicode{0}Hyphen' -f [System.Char]::ConvertFromUtf32(0x2011)) | ConvertTo-WikiSidebarLinkName | ||
| Returns: "Unicode-Hyphen" | ||
| .INPUTS | ||
| System.String | ||
| .OUTPUTS | ||
| System.String | ||
| .NOTES | ||
| This function is used internally by the New-GitHubWikiSidebar function to | ||
| format link names in the generated sidebar. | ||
| #> | ||
| function ConvertTo-WikiSidebarLinkName | ||
| { | ||
| [CmdletBinding()] | ||
| param | ||
| ( | ||
| [Parameter(Mandatory = $true, ValueFromPipeline = $true, Position = 0)] | ||
| [System.String] | ||
| $Name | ||
| ) | ||
|
|
||
| process | ||
| { | ||
| if ($PSVersionTable.PSVersion -ge '6.0') | ||
| { | ||
| # Replace hyphens with spaces | ||
| $convertedName = $Name -replace '-', ' ' | ||
|
|
||
| # Replace Unicode hyphen (U+2010) with a standard hyphen | ||
| $convertedName = $convertedName -replace [System.Char]::ConvertFromUtf32(0x2011), '-' | ||
| } | ||
| else | ||
| { | ||
| $convertedName = $Name | ||
| } | ||
|
|
||
| return $convertedName | ||
| } | ||
| } |
16 changes: 16 additions & 0 deletions
16
source/Private/Task.Clean_WikiContent_For_GitHub_Publish.build.ps1
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| <# | ||
| .SYNOPSIS | ||
| This is the alias to the build task Clean_WikiContent_For_GitHub_Publish | ||
| script file. | ||
| .DESCRIPTION | ||
| This makes available the alias 'Task.Clean_WikiContent_For_GitHub_Publish' | ||
| that is exported in the module manifest so that the build task can be | ||
| correctly imported using for example Invoke-Build. | ||
| .NOTES | ||
| This is using the pattern lined out in the Invoke-Build repository | ||
| https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import. | ||
| #> | ||
|
|
||
| Set-Alias -Name 'Task.Clean_WikiContent_For_GitHub_Publish' -Value "$PSScriptRoot/tasks/Clean_WikiContent_For_GitHub_Publish.build.ps1" |
16 changes: 16 additions & 0 deletions
16
source/Private/Task.Prepare_Markdown_Filenames_For_GitHub_Publish.build.ps1
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| <# | ||
| .SYNOPSIS | ||
| This is the alias to the build task Prepare_Markdown_Filenames_For_GitHub_Publish | ||
| script file. | ||
| .DESCRIPTION | ||
| This makes available the alias 'Task.Prepare_Markdown_Filenames_For_GitHub_Publish' | ||
| that is exported in the module manifest so that the build task can be correctly | ||
| imported using for example Invoke-Build. | ||
| .NOTES | ||
| This is using the pattern lined out in the Invoke-Build repository | ||
| https://github.com/nightroman/Invoke-Build/tree/master/Tasks/Import. | ||
| #> | ||
|
|
||
| Set-Alias -Name 'Task.Prepare_Markdown_Filenames_For_GitHub_Publish' -Value "$PSScriptRoot/tasks/Prepare_Markdown_Filenames_For_GitHub_Publish.build.ps1" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file was deleted.
Oops, something went wrong.
142 changes: 142 additions & 0 deletions
142
source/tasks/Clean_WikiContent_For_GitHub_Publish.build.ps1
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,142 @@ | ||
| <# | ||
| .SYNOPSIS | ||
| This is a build task that modifies the wiki content to enhance the content | ||
| for use in GitHub repository Wikis. | ||
| .PARAMETER ProjectPath | ||
| The root path to the project. Defaults to $BuildRoot. | ||
| .PARAMETER OutputDirectory | ||
| The base directory of all output. Defaults to folder 'output' relative to | ||
| the $BuildRoot. | ||
| .PARAMETER BuiltModuleSubdirectory | ||
| Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName). | ||
| This is especially useful when you want to build DSC Resources, but you don't want the | ||
| `Get-DscResource` command to find several instances of the same DSC Resources because | ||
| of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`). | ||
| In most cases I would recommend against setting $BuiltModuleSubdirectory. | ||
| .PARAMETER VersionedOutputDirectory | ||
| Whether the Module is built with its versioned Subdirectory, as you would see it on a System. | ||
| For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` | ||
| .PARAMETER ProjectName | ||
| The project name. Defaults to the empty string. | ||
| .PARAMETER SourcePath | ||
| The path to the source folder name. Defaults to the empty string. | ||
| The task does not use this parameter, see the notes below. | ||
| .PARAMETER DocOutputFolder | ||
| The path to the where the markdown documentation is written. Defaults to the | ||
| folder `./output/WikiContent`. | ||
| .PARAMETER BuildInfo | ||
| The build info object from ModuleBuilder. Defaults to an empty hashtable. | ||
| .NOTES | ||
| This is a build task that is primarily meant to be run by Invoke-Build but | ||
| wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler). | ||
| Parameter SourcePath is intentionally added to the task even if it is not used, | ||
| otherwise the tests fails. Most likely because the script Set-SamplerTaskVariable | ||
| expects the variable to always be available. | ||
| #> | ||
| [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('DscResource.AnalyzerRules/Measure-ParameterBlockParameterAttribute', '', Justification = 'For boolean values when using (property $true $false) fails in conversion between string and boolean when environment variable is used if set as advanced parameter ([Parameter()])')] | ||
| param | ||
| ( | ||
| [Parameter()] | ||
| [System.String] | ||
| $ProjectPath = (property ProjectPath $BuildRoot), | ||
|
|
||
| [Parameter()] | ||
| [System.String] | ||
| $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), | ||
|
|
||
| [Parameter()] | ||
| [System.String] | ||
| $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''), | ||
|
|
||
| [Parameter()] | ||
| [System.Management.Automation.SwitchParameter] | ||
| $VersionedOutputDirectory = (property VersionedOutputDirectory $true), | ||
|
|
||
| [Parameter()] | ||
| [System.String] | ||
| $ProjectName = (property ProjectName ''), | ||
|
|
||
| [Parameter()] | ||
| [System.String] | ||
| $SourcePath = (property SourcePath ''), | ||
|
|
||
| [Parameter()] | ||
| [System.String] | ||
| $DocOutputFolder = (property DocOutputFolder 'WikiContent'), | ||
|
|
||
| [Parameter()] | ||
| [System.Management.Automation.SwitchParameter] | ||
| $RemoveTopLevelHeader = (property RemoveTopLevelHeader $true), | ||
|
|
||
| [Parameter()] | ||
| [System.Collections.Hashtable] | ||
| $BuildInfo = (property BuildInfo @{ }) | ||
| ) | ||
|
|
||
| # Synopsis: Modifies the wiki content to enhance the content for use in GitHub repository Wikis. | ||
| Task Clean_WikiContent_For_GitHub_Publish { | ||
| if ($PSVersionTable.PSVersion -lt '6.0') | ||
| { | ||
| Write-Warning -Message 'This task is not supported in Windows PowerShell.' | ||
|
|
||
| return | ||
| } | ||
|
|
||
| # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. | ||
| . Set-SamplerTaskVariable | ||
|
|
||
| $DocOutputFolder = Get-SamplerAbsolutePath -Path $DocOutputFolder -RelativeTo $OutputDirectory | ||
|
|
||
| "`tDocs output folder path = '$DocOutputFolder'" | ||
| '' | ||
|
|
||
| if ($RemoveTopLevelHeader) | ||
| { | ||
| $markdownFiles = Get-ChildItem -Path $DocOutputFolder -Filter '*.md' | ||
|
|
||
| Write-Build -Color 'Magenta' -Text 'Removing top level header from markdown files if it is the same as the filename.' | ||
|
|
||
| $markdownFiles | | ||
| ForEach-Object -Process { | ||
| $content = Get-Content -Path $_.FullName -Raw | ||
|
|
||
| $hasTopHeader = $content -match '(?m)^#\s+([^\r\n]+)' | ||
|
|
||
| $baseNameWithoutNonBreakingHyphen = $_.BaseName -replace [System.Char]::ConvertFromUtf32(0x2011), '-' | ||
|
|
||
| if ($hasTopHeader -and $Matches[1] -eq $baseNameWithoutNonBreakingHyphen) | ||
| { | ||
| Write-Build -Color DarkGray -Text ('Top level header is the same as the filename. Removing top level header from: {0}' -f $_.Name) | ||
|
|
||
| <# | ||
| Remove only the top level header (# Header) and any empty lines | ||
| following it. The regex should only target the first header found, | ||
| without affecting later top level headers. | ||
| #> | ||
| $content = $content -replace '(?m)^#\s+(.*)\s*', '' | ||
|
|
||
| # Save the updated content back to the file | ||
| Set-Content -Path $_.FullName -Value $content | ||
| } | ||
| elseif ($hasTopHeader) | ||
| { | ||
| Write-Build -Color DarkGray -Text ('Top level header is different from the filename. Skipping: {0}' -f $_.Name) | ||
| } | ||
| else | ||
| { | ||
| Write-Build -Color DarkGray -Text ('No top level header found in: {0}' -f $_.Name) | ||
| } | ||
| } | ||
| } | ||
| } |
Oops, something went wrong.