Skip to content

Commit bd55b82

Browse files
glennsartiglennsarti
committed
(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
1 parent f93653b commit bd55b82

File tree

4 files changed

+113
-15
lines changed

4 files changed

+113
-15
lines changed

‎.gitignore

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -29,9 +29,6 @@ registered_data.ini
2929
.dotnet/
3030
module/Plaster
3131
module/PSScriptAnalyzer
32-
docs/_site/
33-
docs/_repo/
34-
docs/metadata/
3532
*.zip
3633

3734
# Generated build info file
@@ -74,3 +71,9 @@ module/PowerShellEditorServices/Third\ Party\ Notices.txt
7471

7572
# JetBrains generated file (Rider, intelliJ)
7673
.idea/
74+
75+
# Docfx generation
76+
docs/_site/
77+
docs/_repo/
78+
docs/metadata/
79+
tools/docfx

‎PowerShellEditorServices.build.ps1

Lines changed: 48 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,9 @@ param(
1111

1212
[string]$ModulesJsonPath = "$PSScriptRoot/modules.json",
1313

14-
[string]$DefaultModuleRepository = "PSGallery"
14+
[string]$DefaultModuleRepository = "PSGallery",
15+
16+
[switch]$ModifyMSBuildEnvVars
1517
)
1618

1719
#Requires -Modules @{ModuleName="InvokeBuild";ModuleVersion="3.2.1"}
@@ -26,7 +28,7 @@ if ($PSVersionTable.PSEdition -ne "Core") {
2628
Add-Type -Assembly System.IO.Compression.FileSystem
2729
}
2830

29-
task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestPowerShellApi, PackageNuGet {
31+
task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestPowerShellApi, PackageNuGet, BuildDocs, ServeDocs {
3032

3133
$requiredSdkVersion = "2.0.0"
3234

@@ -94,6 +96,42 @@ task SetupDotNet -Before Clean, Build, TestHost, TestServer, TestProtocol, TestP
9496
$env:PATH = $dotnetExeDir + [System.IO.Path]::PathSeparator + $env:PATH
9597
$env:DOTNET_INSTALL_DIR = $dotnetExeDir
9698
}
99+
if ($ModifyMSBuildEnvVars.IsPresent -and !$script:IsUnix) {
100+
# Some operations require the correct SDK to be set in the environment e.g. Docfx
101+
# Only valid on Windows
102+
$dotnetExeDir = [System.IO.Path]::GetDirectoryName($script:dotnetExe)
103+
$SDKPath = [System.IO.Path]::Combine($dotnetExeDir, "sdk")
104+
105+
$SDKVersionPath = ''
106+
Get-ChildItem -Path $SDKPath -Directory | ForEach-Object -Process {
107+
if ($SDKVersionPath -eq '') {
108+
$TestPath = Join-Path -Path $_.Fullname -ChildPath 'Sdks'
109+
if (Test-Path -Path $TestPath) { $SDKVersionPath = $_.Fullname }
110+
}
111+
}
112+
if (-not [string]::IsNullOrEmpty($SDKVersionPath)) {
113+
$ENV:MSBuildSDKsPath = Join-Path -Path $SDKVersionPath -ChildPath 'Sdks'
114+
$ENV:MSBuildExtensionsPath = $SDKVersionPath
115+
$ENV:MSBUILD_EXE_PATH = Join-Path -Path $SDKVersionPath -ChildPath 'MSBuild.dll'
116+
117+
# # Get currently installed VS Verion
118+
# DocFX may require - https://github.com/dotnet/docfx/issues/2491#issuecomment-371722477
119+
# $VisualStudioVersion = (Get-ItemProperty "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\VisualStudio\SxS\VS7" |
120+
# Get-Member -MemberType NoteProperty |
121+
# Where-Object { $_.Name -notlike 'PS*'} |
122+
# Sort-Object |
123+
# Select -First 1).Name
124+
# # Get Visual Studio install path
125+
# $VSINSTALLDIR = $(Get-ItemProperty "Registry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\Microsoft\VisualStudio\SxS\VS7").$VisualStudioVersion;
126+
# # Add Visual Studio environment variables
127+
# $env:VisualStudioVersion = $VisualStudioVersion;
128+
# $env:VSINSTALLDIR = $VSINSTALLDIR;
129+
130+
Write-Host "`n### Using dotnet SDK at path $SDKVersionPath" -ForegroundColor Green
131+
} else {
132+
Throw "Unable to find any SDKs in path $SDKPath"
133+
}
134+
}
97135

98136
Write-Host "`n### Using dotnet v$(& $script:dotnetExe --version) at path $script:dotnetExe`n" -ForegroundColor Green
99137
}
@@ -386,5 +424,13 @@ task UploadArtifacts -If ($script:IsCIBuild) {
386424
}
387425
}
388426

427+
task BuildDocs -If { !$script:IsUnix } {
428+
exec { & scripts\BuildDocs.ps1 -Clean }
429+
}
430+
431+
task ServeDocs -If { !$script:IsUnix } {
432+
exec { & scripts\BuildDocs.ps1 -Clean -Serve }
433+
}
434+
389435
# The default task is to run the entire CI build
390436
task . GetProductVersion, Clean, Build, TestPowerShellApi, CITest, BuildCmdletHelp, PackageNuGet, PackageModule, UploadArtifacts

‎docs/docfx.json

Lines changed: 25 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,27 @@
44
"src": [
55
{
66
"files": [ "*.csproj" ],
7-
"cwd": "../src/PowerShellEditorServices",
7+
"src": "../src/PowerShellEditorServices",
8+
"exclude": [ "**/obj/**", "**/bin/**" ]
9+
},
10+
{
11+
"files": [ "*.csproj" ],
12+
"src": "../src/PowerShellEditorServices.Channel.WebSocket",
13+
"exclude": [ "**/obj/**", "**/bin/**" ]
14+
},
15+
{
16+
"files": [ "*.csproj" ],
17+
"src": "../src/PowerShellEditorServices.Host",
18+
"exclude": [ "**/obj/**", "**/bin/**" ]
19+
},
20+
{
21+
"files": [ "*.csproj" ],
22+
"src": "../src/PowerShellEditorServices.Protocol",
23+
"exclude": [ "**/obj/**", "**/bin/**" ]
24+
},
25+
{
26+
"files": [ "*.csproj" ],
27+
"src": "../src/PowerShellEditorServices.VSCode",
828
"exclude": [ "**/obj/**", "**/bin/**" ]
929
}
1030
],
@@ -14,21 +34,21 @@
1434
"build": {
1535
"content": [
1636
{
17-
"cwd": "metadata/api",
37+
"src": "metadata/api",
1838
"files": [
1939
"**/**.yml"
2040
],
2141
"dest": "api"
2242
},
2343
{
24-
"cwd": "../",
44+
"src": "../",
2545
"files": [
2646
"CONTRIBUTING.md",
2747
"CHANGELOG.md"
2848
]
2949
},
3050
{
31-
"cwd": ".",
51+
"src": ".",
3252
"files": [
3353
"toc.yml",
3454
"index.md",
@@ -66,4 +86,4 @@
6686
"dest": "_site",
6787
"template": [ "default", "template" ]
6888
}
69-
}
89+
}

‎scripts/BuildDocs.ps1

Lines changed: 34 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,47 @@ $docsRepoPath = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\docs\_repo")
1111
# Ensure the tools path exists
1212
mkdir $toolsPath -Force | Out-Null
1313

14+
if (![System.IO.File]::Exists($docfxBinPath)) {
15+
mkdir $docfxBinPath -Force | Out-Null
16+
}
17+
1418
if (![System.IO.File]::Exists($docfxExePath)) {
1519
# Download DocFX
16-
Remove-Item -Path "$docfxBinPath" -Force -ErrorAction Stop | Out-Null
17-
(new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v1.8/docfx.zip', "$docfxZipPath")
20+
if (Test-Path -Path $docfxBinPath) { Remove-Item -Path "$docfxBinPath" -Force -ErrorAction Stop | Out-Null }
21+
# Github uses TLS 1.2
22+
$originalSecurityProtocol = [Net.ServicePointManager]::SecurityProtocol
23+
try {
24+
[Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor [Net.SecurityProtocolType]::Tls12
25+
Write-Verbose "Downloading docfx..."
26+
# The docFX 1.x release does generate documentation but is incomplete as it doesn't understand dotNet 2.1
27+
# The docFX 2.x release errors during generation as it doesn't understand dotNet 2.1
28+
# 2.1 support seems to be slated for docfx 3.x release - https://github.com/dotnet/docfx/projects/1
29+
#
30+
# For now use the 1.x series of docfx
31+
(new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v1.9.4/docfx.zip', "$docfxZipPath")
32+
#(new-object net.webclient).DownloadFile('https://github.com/dotnet/docfx/releases/download/v2.40.3/docfx.zip', "$docfxZipPath")
1833

19-
# Extract the archive
20-
Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop"
34+
# Extract the archive
35+
Expand-Archive $docfxZipPath -DestinationPath $docfxBinPath -Force -ErrorAction "Stop"
36+
}
37+
Finally {
38+
[Net.ServicePointManager]::SecurityProtocol = $originalSecurityProtocol
39+
}
2140
}
2241

2342
# Clean the _site folder if necessary
2443
if ($Clean.IsPresent) {
25-
Remove-Item -Path $sitePath -Force -Recurse | Out-Null
44+
if (Test-Path -Path $sitePath) { Remove-Item -Path $sitePath -Force -Recurse | Out-Null }
45+
46+
# Clean docfx object caches
47+
@("src\PowerShellEditorServices",
48+
"src\PowerShellEditorServices.Channel.WebSocket",
49+
"src\PowerShellEditorServices.Host",
50+
"src\PowerShellEditorServices.Protocol",
51+
"src\PowerShellEditorServices.VSCode") | ForEach-Object -Process {
52+
$docCache = [System.IO.Path]::GetFullPath("$PSScriptRoot\..\" + $_ + "\obj\xdoc")
53+
if ([System.IO.Directory]::Exists($docCache)) { Remove-Item -Force -Recurse -Path $docCache | Out-Null }
54+
}
2655
}
2756

2857
# Build the metadata for the C# API

0 commit comments

Comments
 (0)