(GH-799) Revive docfx scripts

Previously the document generation scripts for docfx were broken e.g. Unable to
download docfx from github due to TLS.  This commit;
* Updates the BuildDocs script to properly clean and download docfx from Github
* Updates the docfx.json file to use the correct naming (cwd -> src) and to
  use the correct project files
* Updates gitignore to ignore docfx working directory
* Adds two build tasks (BuildDocs and ServeDocs) to build and serve
  autogenerated documentation
* Adds additional configuration switch for Invoke-Build for legacy applications,
  like docfx, which use MSBuild as a library but it needs the dotNet Core
  versions of MSBuild instead of VS 2015/2017

Author: glennsarti

.gitignore

@@ -29,9 +29,6 @@ registered_data.ini
 .dotnet/
 module/Plaster
 module/PSScriptAnalyzer
-docs/_site/
-docs/_repo/
-docs/metadata/
 *.zip
 
 # Generated build info file
@@ -74,3 +71,9 @@ module/PowerShellEditorServices/Third\ Party\ Notices.txt
 
 # JetBrains generated file (Rider, intelliJ)
 .idea/
+
+# Docfx generation
+docs/_site/
+docs/_repo/
+docs/metadata/
+tools/docfx

PowerShellEditorServices.build.ps1

@@ -11,7 +11,9 @@ param(
 
     [string]$ModulesJsonPath = "$PSScriptRoot/modules.json",
 
-    [string]$DefaultModuleRepository = "PSGallery"
+    [string]$DefaultModuleRepository = "PSGallery",
+
+    [switch]$ModifyMSBuildEnvVars = $false
 )
 
 #Requires -Modules @{ModuleName="InvokeBuild";ModuleVersion="3.2.1"}
@@ -26,7 +28,7 @@ if ($PSVersionTable.PSEdition -ne "Core") {
     Add-Type -Assembly System.IO.Compression.FileSystem
 }
 
-task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestPowerShellApi, PackageNuGet {
+task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestPowerShellApi, PackageNuGet, BuildDocs, ServeDocs {
 
     $requiredSdkVersion = "2.0.0"
 
@@ -94,6 +96,42 @@ task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestP
         $env:PATH = $dotnetExeDir + [System.IO.Path]::PathSeparator + $env:PATH
         $env:DOTNET_INSTALL_DIR = $dotnetExeDir
     }
+    if ($ModifyMSBuildEnvVars -and !$script:IsUnix) {
+        # Some operations require the correct SDK to be set in the environment e.g. Docfx
+        # Only valid on Windows
+        $dotnetExeDir = [System.IO.Path]::GetDirectoryName($script:dotnetExe)
+        $SDKPath = [System.IO.Path]::Combine($dotnetExeDir, "sdk")
+
+        $SDKVerionPath = ''
+        Get-ChildItem -Path $SDKPath -Directory | ForEach-Object -Process {
+            if ($SDKVerionPath -eq '') {
+                $TestPath = Join-Path -Path $_.Fullname -ChildPath 'Sdks'
+                if (Test-Path -Path $TestPath) { $SDKVerionPath = $_.Fullname }
+            }
+        }
+        if ($SDKVerionPath -ne '') {
+            $ENV:MSBuildSDKsPath = Join-Path -Path $SDKVerionPath -ChildPath 'Sdks'
+            $ENV:MSBuildExtensionsPath = $SDKVerionPath
+            $ENV:MSBUILD_EXE_PATH = Join-Path -Path $SDKVerionPath -ChildPath 'MSBuild.dll'
+
+            # # Get currently installed VS Verion
+            # DocFX may require - https://github.com/dotnet/docfx/issues/2491#issuecomment-371722477
+            # $VisualStudioVersion = (Get-ItemProperty "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\VisualStudio\SxS\VS7" |
+            #     Get-Member -MemberType NoteProperty |
+            #     Where-Object { $_.Name -notlike 'PS*'} |
+            #     Sort-Object |
+            #     Select -First 1).Name
+            # # Get Visual Studio install path
+            # $VSINSTALLDIR =  $(Get-ItemProperty "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\VisualStudio\SxS\VS7").$VisualStudioVersion;
+            # # Add Visual Studio environment variables
+            # $env:VisualStudioVersion = $VisualStudioVersion;
+            # $env:VSINSTALLDIR = $VSINSTALLDIR;
+
+            Write-Host "`n### Using dotnet SDK at path $SDKVerionPath" -ForegroundColor Green
+        } else {
+            Throw "Unable to find any SDKs in path $SDKPath"
+        }
+    }
 
     Write-Host "`n### Using dotnet v$(& $script:dotnetExe --version) at path $script:dotnetExe`n" -ForegroundColor Green
 }
@@ -386,5 +424,13 @@ task UploadArtifacts -If ($script:IsCIBuild) {
     }
 }
 
+task BuildDocs -If { !$script:IsUnix } {
+    exec { & scripts\BuildDocs.ps1 -Clean }
+}
+
+task ServeDocs -If { !$script:IsUnix } {
+    exec { & scripts\BuildDocs.ps1 -Clean -Serve }
+}
+
 # The default task is to run the entire CI build
 task . GetProductVersion, Clean, Build, TestPowerShellApi, CITest, BuildCmdletHelp, PackageNuGet, PackageModule, UploadArtifacts

docs/docfx.json

@@ -4,7 +4,27 @@
       "src": [
         {
           "files": [ "*.csproj" ],
-          "cwd": "../src/PowerShellEditorServices",
+          "src": "../src/PowerShellEditorServices",
+          "exclude": [ "**/obj/**", "**/bin/**" ]
+        },
+        {
+          "files": [ "*.csproj" ],
+          "src": "../src/PowerShellEditorServices.Channel.WebSocket",
+          "exclude": [ "**/obj/**", "**/bin/**" ]
+        },
+        {
+          "files": [ "*.csproj" ],
+          "src": "../src/PowerShellEditorServices.Host",
+          "exclude": [ "**/obj/**", "**/bin/**" ]
+        },
+        {
+          "files": [ "*.csproj" ],
+          "src": "../src/PowerShellEditorServices.Protocol",
+          "exclude": [ "**/obj/**", "**/bin/**" ]
+        },
+        {
+          "files": [ "*.csproj" ],
+          "src": "../src/PowerShellEditorServices.VSCode",
           "exclude": [ "**/obj/**", "**/bin/**" ]
         }
       ],
@@ -14,21 +34,21 @@
   "build": {
     "content": [
       {
-        "cwd": "metadata/api",
+        "src": "metadata/api",
         "files": [
           "**/**.yml"
         ],
         "dest": "api"
       },
       {
-        "cwd": "../",
+        "src": "../",
         "files": [
           "CONTRIBUTING.md",
           "CHANGELOG.md"
         ]
       },
       {
-        "cwd":  ".",
+        "src":  ".",
         "files": [
           "toc.yml",
           "index.md",
@@ -66,4 +86,4 @@
     "dest": "_site",
     "template": [ "default", "template" ]
   }
-}
+}

scripts/BuildDocs.ps1

@@ -11,18 +11,41 @@ $docsRepoPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\_repo")
 # Ensure the tools path exists
 mkdir $toolsPath -Force | Out-Null
 
+if (![System.IO.File]::Exists($docfxBinPath)) {
+    mkdir $docfxBinPath -Force | Out-Null
+}
+
 if (![System.IO.File]::Exists($docfxExePath)) {
     # Download DocFX
-    Remove-Item -Path "$docfxBinPath" -Force -ErrorAction Stop | Out-Null
-    (new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v1.8/docfx.zip', "$docfxZipPath")
+    if (Test-Path -Path $docfxBinPath) { Remove-Item -Path "$docfxBinPath" -Force -ErrorAction Stop | Out-Null }
+    # Github uses TLS 1.2
+    [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+    Write-Verbose "Downloading docfx..."
+    # The docFX 1.x release does generate documentation but is incomplete as it doesn't understand dotNet 2.1
+    # The docFX 2.x release errors during generation as it doesn't understand dotNet 2.1
+    # 2.1 support seems to be slated for docfx 3.x release - https://github.com/dotnet/docfx/projects/1
+    #
+    # For now use the 1.x series of docfx
+    (new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v1.9.4/docfx.zip', "$docfxZipPath")
+    #(new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v2.40.3/docfx.zip', "$docfxZipPath")
 
     # Extract the archive
     Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop"
 }
 
 # Clean the _site folder if necessary
 if ($Clean.IsPresent) {
-    Remove-Item -Path $sitePath -Force -Recurse | Out-Null
+    if (Test-Path -Path $sitePath) { Remove-Item -Path $sitePath -Force -Recurse | Out-Null }
+
+    # Clean docfx object caches
+    @("src\PowerShellEditorServices",
+      "src\PowerShellEditorServices.Channel.WebSocket",
+      "src\PowerShellEditorServices.Host",
+      "src\PowerShellEditorServices.Protocol",
+      "src\PowerShellEditorServices.VSCode") | ForEach-Object -Process {
+        $docCache = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\" + $_ + "\obj\xdoc")
+        if ([System.IO.Directory]::Exists($docCache)) { Remove-Item -Force -Recurse -Path $docCache | Out-Null }
+    }
 }
 
 # Build the metadata for the C# API