|
| 1 | +<# |
| 2 | + .SYNOPSIS |
| 3 | + This is a build task that modifies the wiki content to enhance the content |
| 4 | + for use in GitHub repository Wikis. |
| 5 | +
|
| 6 | + .PARAMETER ProjectPath |
| 7 | + The root path to the project. Defaults to $BuildRoot. |
| 8 | +
|
| 9 | + .PARAMETER OutputDirectory |
| 10 | + The base directory of all output. Defaults to folder 'output' relative to |
| 11 | + the $BuildRoot. |
| 12 | +
|
| 13 | + .PARAMETER BuiltModuleSubdirectory |
| 14 | + Sub folder where you want to build the Module to (instead of $OutputDirectory/$ModuleName). |
| 15 | + This is especially useful when you want to build DSC Resources, but you don't want the |
| 16 | + `Get-DscResource` command to find several instances of the same DSC Resources because |
| 17 | + of the overlapping $Env:PSmodulePath (`$buildRoot/output` for the built module and `$buildRoot/output/RequiredModules`). |
| 18 | +
|
| 19 | + In most cases I would recommend against setting $BuiltModuleSubdirectory. |
| 20 | +
|
| 21 | + .PARAMETER VersionedOutputDirectory |
| 22 | + Whether the Module is built with its versioned Subdirectory, as you would see it on a System. |
| 23 | + For instance, if VersionedOutputDirectory is $true, the built module's ModuleBase would be: `output/MyModuleName/2.0.1/` |
| 24 | +
|
| 25 | + .PARAMETER ProjectName |
| 26 | + The project name. Defaults to the empty string. |
| 27 | +
|
| 28 | + .PARAMETER SourcePath |
| 29 | + The path to the source folder name. Defaults to the empty string. |
| 30 | + The task does not use this parameter, see the notes below. |
| 31 | +
|
| 32 | + .PARAMETER DocOutputFolder |
| 33 | + The path to the where the markdown documentation is written. Defaults to the |
| 34 | + folder `./output/WikiContent`. |
| 35 | +
|
| 36 | + .PARAMETER BuildInfo |
| 37 | + The build info object from ModuleBuilder. Defaults to an empty hashtable. |
| 38 | +
|
| 39 | + .NOTES |
| 40 | + This is a build task that is primarily meant to be run by Invoke-Build but |
| 41 | + wrapped by the Sampler project's build.ps1 (https://github.com/gaelcolas/Sampler). |
| 42 | +
|
| 43 | + Parameter SourcePath is intentionally added to the task even if it is not used, |
| 44 | + otherwise the tests fails. Most likely because the script Set-SamplerTaskVariable |
| 45 | + expects the variable to always be available. |
| 46 | +#> |
| 47 | +[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()])')] |
| 48 | +param |
| 49 | +( |
| 50 | + [Parameter()] |
| 51 | + [System.String] |
| 52 | + $ProjectPath = (property ProjectPath $BuildRoot), |
| 53 | + |
| 54 | + [Parameter()] |
| 55 | + [System.String] |
| 56 | + $OutputDirectory = (property OutputDirectory (Join-Path $BuildRoot 'output')), |
| 57 | + |
| 58 | + [Parameter()] |
| 59 | + [System.String] |
| 60 | + $BuiltModuleSubdirectory = (property BuiltModuleSubdirectory ''), |
| 61 | + |
| 62 | + [Parameter()] |
| 63 | + [System.Management.Automation.SwitchParameter] |
| 64 | + $VersionedOutputDirectory = (property VersionedOutputDirectory $true), |
| 65 | + |
| 66 | + [Parameter()] |
| 67 | + [System.String] |
| 68 | + $ProjectName = (property ProjectName ''), |
| 69 | + |
| 70 | + [Parameter()] |
| 71 | + [System.String] |
| 72 | + $SourcePath = (property SourcePath ''), |
| 73 | + |
| 74 | + [Parameter()] |
| 75 | + [System.String] |
| 76 | + $DocOutputFolder = (property DocOutputFolder 'WikiContent'), |
| 77 | + |
| 78 | + [Parameter()] |
| 79 | + [System.Management.Automation.SwitchParameter] |
| 80 | + $RemoveTopLevelHeader = (property RemoveTopLevelHeader $true), |
| 81 | + |
| 82 | + [Parameter()] |
| 83 | + [System.Collections.Hashtable] |
| 84 | + $BuildInfo = (property BuildInfo @{ }) |
| 85 | +) |
| 86 | + |
| 87 | +# Synopsis: Modifies the wiki content to enhance the content for use in GitHub repository Wikis. |
| 88 | +Task Clean_WikiContent_For_GitHub_Publish { |
| 89 | + if ($PSVersionTable.PSVersion -lt '6.0') |
| 90 | + { |
| 91 | + Write-Warning -Message 'This task is not supported in Windows PowerShell.' |
| 92 | + |
| 93 | + return |
| 94 | + } |
| 95 | + |
| 96 | + # Get the values for task variables, see https://github.com/gaelcolas/Sampler#task-variables. |
| 97 | + . Set-SamplerTaskVariable |
| 98 | + |
| 99 | + $DocOutputFolder = Get-SamplerAbsolutePath -Path $DocOutputFolder -RelativeTo $OutputDirectory |
| 100 | + |
| 101 | + "`tDocs output folder path = '$DocOutputFolder'" |
| 102 | + '' |
| 103 | + |
| 104 | + if ($RemoveTopLevelHeader) |
| 105 | + { |
| 106 | + $markdownFiles = Get-ChildItem -Path $DocOutputFolder -Filter '*.md' |
| 107 | + |
| 108 | + Write-Build -Color 'Magenta' -Text 'Removing top level header from markdown files if it is the same as the filename.' |
| 109 | + |
| 110 | + $markdownFiles | |
| 111 | + ForEach-Object -Process { |
| 112 | + $content = Get-Content -Path $_.FullName -Raw |
| 113 | + |
| 114 | + $hasTopHeader = $content -match '(?m)^#\s+([^\r\n]+)' |
| 115 | + |
| 116 | + $baseNameWithoutNonBreakingHyphen = $_.BaseName -replace [System.Char]::ConvertFromUtf32(0x2011), '-' |
| 117 | + |
| 118 | + if ($hasTopHeader -and $Matches[1] -eq $baseNameWithoutNonBreakingHyphen) |
| 119 | + { |
| 120 | + Write-Build -Color DarkGray -Text ('Top level header is the same as the filename. Removing top level header from: {0}' -f $_.Name) |
| 121 | + |
| 122 | + <# |
| 123 | + Remove only the top level header (# Header) and any empty lines |
| 124 | + following it. The regex should only target the first header found, |
| 125 | + without affecting later top level headers. |
| 126 | + #> |
| 127 | + $content = $content -replace '(?m)^#\s+(.*)\s*', '' |
| 128 | + |
| 129 | + # Save the updated content back to the file |
| 130 | + Set-Content -Path $_.FullName -Value $content |
| 131 | + } |
| 132 | + elseif ($hasTopHeader) |
| 133 | + { |
| 134 | + Write-Build -Color DarkGray -Text ('Top level header is different from the filename. Skipping: {0}' -f $_.Name) |
| 135 | + } |
| 136 | + else |
| 137 | + { |
| 138 | + Write-Build -Color DarkGray -Text ('No top level header found in: {0}' -f $_.Name) |
| 139 | + } |
| 140 | + } |
| 141 | + } |
| 142 | +} |
0 commit comments