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..e5ab7a45d 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,29 @@ 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' + + 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 +411,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