Update build as we move help content to PowerShell-Docs (#1537)

Author: daxian-dbw

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,17 @@
+<!-- Anything that looks like this is a comment and can't be seen after the Pull Request is created. -->
+
+# PR Summary
+
+<!-- Summarize your PR between here and the checklist. -->
+
+## PR Checklist
+
+- [ ] PR has a meaningful title
+    - Use the present tense and imperative mood when describing your changes
+- [ ] Summarized changes
+- [ ] Make sure you've added one or more new tests
+- **User-facing changes**
+    - [ ] Not Applicable
+    - **OR**
+    - [ ] Documentation needed at [PowerShell-Docs](https://github.com/MicrosoftDocs/PowerShell-Docs)
+        - [ ] Doc Issue filed: <!-- Number/link of that issue here -->

.vsts-ci/releaseBuild.yml

@@ -46,8 +46,9 @@ jobs:
         Write-Host ("sending: " + $vstsCommandString)
         Write-Host "##$vstsCommandString"
       }
+      Write-Host "PS Version: $($($PSVersionTable.PSVersion))"
       $(Build.SourcesDirectory)\build.ps1 -Bootstrap
-      $(Build.SourcesDirectory)\build.ps1 -Configuration Release -Framework net461
+      $(Build.SourcesDirectory)\build.ps1 -Configuration Release -Framework net461 -CheckHelpContent
       # Get module version
       $psd1Data = Import-PowerShellDataFile -Path $(Build.SourcesDirectory)\bin\Release\PSReadLine\PSReadLine.psd1
       $moduleVersion = $psd1Data.ModuleVersion

PSReadLine.build.ps1

@@ -16,13 +16,13 @@
 
 [CmdletBinding()]
 param(
-    [switch]$Install,
-
     [ValidateSet("Debug", "Release")]
     [string]$Configuration = (property Configuration Release),
 
     [ValidateSet("net461", "netcoreapp2.1")]
-    [string]$Framework
+    [string]$Framework,
+
+    [switch]$CheckHelpContent
 )
 
 Import-Module "$PSScriptRoot/tools/helper.psm1"
@@ -41,50 +41,6 @@ function ConvertTo-CRLF([string] $text) {
     $text.Replace("`r`n","`n").Replace("`n","`r`n")
 }
 
-$buildMamlParams = @{
-    Inputs  = { Get-ChildItem docs/*.md }
-    Outputs = "$targetDir/en-US/Microsoft.PowerShell.PSReadLine2.dll-help.xml"
-}
-
-<#
-Synopsis: Generate maml help from markdown
-#>
-task BuildMamlHelp @buildMamlParams {
-    platyPS\New-ExternalHelp docs -Force -OutputPath $targetDir/en-US/Microsoft.PowerShell.PSReadLine2.dll-help.xml
-}
-
-$buildAboutTopicParams = @{
-    Inputs = {
-         Get-ChildItem docs/about_PSReadLine.help.txt
-         "PSReadLine/bin/$Configuration/$Framework/Microsoft.PowerShell.PSReadLine2.dll"
-         "$PSScriptRoot/tools/GenerateFunctionHelp.ps1"
-         "$PSScriptRoot/tools/CheckHelp.ps1"
-    }
-    Outputs = "$targetDir/en-US/about_PSReadLine.help.txt"
-}
-
-<#
-Synopsis: Generate about topic with function help
-#>
-task BuildAboutTopic @buildAboutTopicParams {
-    # This step loads the dll that was just built, so only do that in another process
-    # so the file isn't locked in any way for the rest of the build.
-    $psExePath = Get-PSExePath
-
-    $generatedFunctionHelpFile = New-TemporaryFile
-    & $psExePath -NoProfile -NonInteractive -File $PSScriptRoot/tools/GenerateFunctionHelp.ps1 $Configuration $generatedFunctionHelpFile.FullName
-    assert ($LASTEXITCODE -eq 0) "Generating function help failed"
-
-    $functionDescriptions = Get-Content -Raw $generatedFunctionHelpFile
-    $aboutTopic = Get-Content -Raw $PSScriptRoot/docs/about_PSReadLine.help.txt
-    $newAboutTopic = $aboutTopic -replace '{{FUNCTION_DESCRIPTIONS}}', $functionDescriptions
-    $newAboutTopic = $newAboutTopic -replace "`r`n","`n"
-    $newAboutTopic | Out-File -FilePath $targetDir\en-US\about_PSReadLine.help.txt -NoNewline -Encoding ascii
-
-    & $psExePath -NoProfile -NonInteractive -File $PSScriptRoot/tools/CheckHelp.ps1 $Configuration
-    assert ($LASTEXITCODE -eq 0) "Checking help and function signatures failed"
-}
-
 $binaryModuleParams = @{
     Inputs  = { Get-ChildItem PSReadLine/*.cs, PSReadLine/PSReadLine.csproj, PSReadLine/PSReadLineResources.resx }
     Outputs = "PSReadLine/bin/$Configuration/$Framework/Microsoft.PowerShell.PSReadLine2.dll"
@@ -138,10 +94,25 @@ Synopsis: Run the unit tests
 #>
 task RunTests BuildMainModule, BuildXUnitTests, { Start-TestRun -Configuration $Configuration -Framework $Framework }
 
+<#
+Synopsis: Check if the help content is in sync.
+#>
+task CheckHelpContent -If $CheckHelpContent {
+    # This step loads the dll that was just built, so only do that in another process
+    # so the file isn't locked in any way for the rest of the build.
+    $psExePath = Get-PSExePath
+    & $psExePath -NoProfile -NonInteractive -File $PSScriptRoot/tools/CheckHelp.ps1 $Configuration
+    assert ($LASTEXITCODE -eq 0) "Checking help and function signatures failed"
+}
+
 <#
 Synopsis: Copy all of the files that belong in the module to one place in the layout for installation
 #>
-task LayoutModule BuildMainModule, BuildMamlHelp, {
+task LayoutModule BuildMainModule, {
+    if (-not (Test-Path $targetDir -PathType Container)) {
+        New-Item $targetDir -ItemType Directory -Force > $null
+    }
+
     $extraFiles =
         'License.txt',
         'PSReadLine/Changes.txt',
@@ -192,7 +163,7 @@ task LayoutModule BuildMainModule, BuildMamlHelp, {
     {
         $file.IsReadOnly = $false
     }
-}, BuildAboutTopic
+}, CheckHelpContent
 
 <#
 Synopsis: Zip up the binary for release.

appveyor.yml

@@ -11,16 +11,16 @@ cache:
   - '%HOMEDRIVE%%HOMEPATH%\.nuget\packages -> tools\helper.psm1'
 
 install:
-  - pwsh: ./build.ps1 -Bootstrap
+  - pwsh: |
+      Write-Host "PS Version: $($($PSVersionTable.PSVersion))"
+      ./build.ps1 -Bootstrap
 
 build_script:
   - pwsh: |
       ./build.ps1 -Configuration Release -Framework net461
-      platyPS\Get-HelpPreview .\bin\Release\PSReadLine\en-US\Microsoft.PowerShell.PSReadLine2.dll-help.xml > .\bin\Release\PSReadLine.txt
 
 test_script:
   - pwsh: ./build.ps1 -Test -Configuration Release -Framework net461
 
 artifacts:
   - path: .\bin\Release\PSReadLine.zip
-  - path: .\bin\Release\PSReadLine.txt

az-ci/azure-devops-psreadline.yml

@@ -31,22 +31,16 @@
 #>
 [CmdletBinding()]
 param(
-    [switch]
-    $Clean,
-
-    [switch]
-    $Bootstrap,
-
-    [switch]
-    $Test,
+    [switch] $Clean,
+    [switch] $Bootstrap,
+    [switch] $Test,
+    [switch] $CheckHelpContent,
 
     [ValidateSet("Debug", "Release")]
-    [string]
-    $Configuration = "Debug",
+    [string] $Configuration = "Debug",
 
     [ValidateSet("net461", "netcoreapp2.1")]
-    [string]
-    $Framework
+    [string] $Framework
 )
 
 # Clean step
@@ -66,10 +60,6 @@ if ($Bootstrap) {
     Write-Log "Validate and install missing prerequisits for building ..."
 
     Install-Dotnet
-    if (-not (Get-Module -Name platyPS -ListAvailable)) {
-        Write-Log -Warning "Module 'platyPS' is missing. Installing 'platyPS' ..."
-        Install-Module -Name platyPS -Scope CurrentUser -Force
-    }
     if (-not (Get-Module -Name InvokeBuild -ListAvailable)) {
         Write-Log -Warning "Module 'InvokeBuild' is missing. Installing 'InvokeBuild' ..."
         Install-Module -Name InvokeBuild -Scope CurrentUser -Force
@@ -80,16 +70,15 @@ if ($Bootstrap) {
 
 # Common step required by both build and test
 Find-Dotnet
-if (-not (Get-Module -Name platyPS -ListAvailable)) {
-    throw "Cannot find the 'platyPS' module. Please specify '-Bootstrap' to install build dependencies."
-}
 if (-not (Get-Module -Name InvokeBuild -ListAvailable)) {
     throw "Cannot find the 'InvokeBuild' module. Please specify '-Bootstrap' to install build dependencies."
 }
 
 # Build/Test step
 $buildTask = if ($Test) { "RunTests" } else { "ZipRelease" }
-
 $arguments = @{ Task = $buildTask; Configuration = $Configuration }
+
 if ($Framework) { $arguments.Add("Framework", $Framework) }
+if ($CheckHelpContent) { $arguments.Add("CheckHelpContent", $true) }
+
 Invoke-Build @arguments