From ddb4899acd39a484d2ca3a6e6b6a5b4172a6e1fb Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Mon, 26 Nov 2018 12:12:26 +0800 Subject: [PATCH 1/2] (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 --- .gitignore | 9 ++++-- PowerShellEditorServices.build.ps1 | 50 ++++++++++++++++++++++++++++-- docs/docfx.json | 30 +++++++++++++++--- scripts/BuildDocs.ps1 | 40 ++++++++++++++++++++---- 4 files changed, 113 insertions(+), 16 deletions(-) diff --git a/.gitignore b/.gitignore index 088159d3d..1e0e0c06a 100644 --- a/.gitignore +++ b/.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 diff --git a/PowerShellEditorServices.build.ps1 b/PowerShellEditorServices.build.ps1 index 2e5038fca..72b25dce8 100644 --- a/PowerShellEditorServices.build.ps1 +++ b/PowerShellEditorServices.build.ps1 @@ -11,7 +11,9 @@ param( [string]$ModulesJsonPath = "$PSScriptRoot/modules.json", - [string]$DefaultModuleRepository = "PSGallery" + [string]$DefaultModuleRepository = "PSGallery", + + [switch]$ModifyMSBuildEnvVars ) #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.IsPresent -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") + + $SDKVersionPath = '' + Get-ChildItem -Path $SDKPath -Directory | ForEach-Object -Process { + if ($SDKVersionPath -eq '') { + $TestPath = Join-Path -Path $_.Fullname -ChildPath 'Sdks' + if (Test-Path -Path $TestPath) { $SDKVersionPath = $_.Fullname } + } + } + if (-not [string]::IsNullOrEmpty($SDKVersionPath)) { + $ENV:MSBuildSDKsPath = Join-Path -Path $SDKVersionPath -ChildPath 'Sdks' + $ENV:MSBuildExtensionsPath = $SDKVersionPath + $ENV:MSBUILD_EXE_PATH = Join-Path -Path $SDKVersionPath -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 $SDKVersionPath" -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 diff --git a/docs/docfx.json b/docs/docfx.json index 8b743686e..d608f7a14 100644 --- a/docs/docfx.json +++ b/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" ] } -} \ No newline at end of file +} diff --git a/scripts/BuildDocs.ps1 b/scripts/BuildDocs.ps1 index 02702dd8d..9be0e4595 100644 --- a/scripts/BuildDocs.ps1 +++ b/scripts/BuildDocs.ps1 @@ -11,18 +11,46 @@ $docsRepoPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\_repo") # Ensure the tools path exists mkdir $toolsPath -Force | Out-Null -if (![System.IO.File]::Exists($docfxExePath)) { +if (!(Test-Path -Path $docfxBinPath)) { + mkdir $docfxBinPath -Force | Out-Null +} + +if (!(Test-Path -Path $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 + $originalSecurityProtocol = [Net.ServicePointManager]::SecurityProtocol + try { + [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [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 (https://github.com/dotnet/docfx/releases/download/v1.9.4/docfx.zip) + # The docFX 2.x release errors during generation as it doesn't understand dotNet 2.1 (https://github.com/dotnet/docfx/releases/download/v2.40.3/docfx.zip) + # 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 + Invoke-WebRequest -Uri 'https://github.com/dotnet/docfx/releases/download/v1.9.4/docfx.zip' -OutFile $docfxZipPath -ErrorAction Stop -UseBasicParsing - # Extract the archive - Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop" + # Extract the archive + Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop" + } + Finally { + [Net.ServicePointManager]::SecurityProtocol = $originalSecurityProtocol + } } # 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 From 570d0c69a52bf2074f94143d80efbc814cd02444 Mon Sep 17 00:00:00 2001 From: Glenn Sarti Date: Wed, 28 Nov 2018 09:51:13 +0800 Subject: [PATCH 2/2] (GH-799) Remove redundant code This commit removes redundant code from the build scripts. --- PowerShellEditorServices.build.ps1 | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/PowerShellEditorServices.build.ps1 b/PowerShellEditorServices.build.ps1 index 72b25dce8..e5ab7a45d 100644 --- a/PowerShellEditorServices.build.ps1 +++ b/PowerShellEditorServices.build.ps1 @@ -114,19 +114,6 @@ task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestP $ENV:MSBuildExtensionsPath = $SDKVersionPath $ENV:MSBUILD_EXE_PATH = Join-Path -Path $SDKVersionPath -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 $SDKVersionPath" -ForegroundColor Green } else { throw "Unable to find any SDKs in path $SDKPath"