Skip to content

(GH-799) Revive docfx scripts #800

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

(GH-799) Revive docfx scripts #800

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ddb4899
(GH-799) Revive docfx scripts
glennsarti Nov 26, 2018
570d0c6
(GH-799) Remove redundant code
glennsarti Nov 28, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 6 additions & 3 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,6 @@ registered_data.ini
.dotnet/
module/Plaster
module/PSScriptAnalyzer
docs/_site/
docs/_repo/
docs/metadata/
*.zip

# Generated build info file
Expand Down Expand Up @@ -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
37 changes: 35 additions & 2 deletions PowerShellEditorServices.build.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
Expand All @@ -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"

Expand Down Expand Up @@ -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
}
Expand Down Expand Up @@ -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
30 changes: 25 additions & 5 deletions docs/docfx.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/**" ]
}
],
Expand All @@ -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",
Expand Down Expand Up @@ -66,4 +86,4 @@
"dest": "_site",
"template": [ "default", "template" ]
}
}
}
40 changes: 34 additions & 6 deletions scripts/BuildDocs.ps1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down