Skip to content

Commit d0315d9

Browse files
VaclavEliasVaclavElias
authored
fix: Temporary custom docfx build (#509)
* test: action.yml - Update workflow to build and install DocFX from fork Switch workflow to use VaclavElias/docfx temp-fix branch for DocFX. Add steps to restore npm dependencies, build site templates, add nightly NuGet source, and build/install DocFX 2.9-stride locally. Retain previous DocFX install steps as comments for reference. * fix: action.yml - Set shell to pwsh for npm and NuGet steps in workflow Added shell: pwsh to npm install, npm build, and NuGet source steps to ensure these actions run with PowerShell in the workflow. This improves consistency and compatibility across the build process. * test: action.yml - Add MSBuild SDK resolver step to GitHub Actions workflow Introduced a PowerShell step after .NET SDK setup to set DOTNET_ROOT and MSBuildSDKsPath environment variables. The step outputs their values and ensures MSBuildSDKsPath exists, improving environment configuration for subsequent workflow steps. * test: Set MSBuildEnableWorkloadResolver in action.yml - Add MSBuildEnableWorkloadResolver=false to GitHub Actions env - Output the variable to logs for visibility - Disables MSBuild workload resolver during workflow execution * docs: docfx.json - Enable C# preview features for docs - Added "LangVersion": "preview" to Stride.BepuPhysics and Stride.Physics project configurations - Allows use of C# preview language features in documentation generation * test: Some projects removed * fix: Comma removed * docs: docfx.json - Add more projects to metadata config - Add multiple Stride engine and core projects to the files array - Add asset and physics projects with net10.0-windows7.0 target - Update metadata structure for improved documentation coverage * feat: action.yml - Add Prebuild Stride step to workflow - Add "Prebuild Stride" step to run dotnet build on build\Stride.sln - Set configuration to Release and working directory to stride - Use PowerShell as the shell for the build step * docs: docfx.json - Update target framework and noRestore - Set noRestore to true to disable package restore * docs: docfx.json - Allow compilation errors in build - Set allowCompilationErrors to true in docfx.json - Enables documentation build even if code samples have errors - Useful for illustrative or incomplete code snippets * test: Add step Install MSVC ARM64/ARM64EC build tools * feat: Add stride-branch input and update action versions - Add stride-branch input to action.yml and stride-docs-test-build.yml - Use stride-branch input in checkout step instead of hardcoded master - Update step names in action.yml for clarity (- Temporary) - Upgrade upload-artifact to v7 in stride-docs-staging-azure.yml - Upgrade download-artifact to v8 in stride-docs-staging-azure.yml - Pass stride-branch input to setup-stride in stride-docs-test-build.yml * docs: Improve CI workflows and add composite setup action - Add NuGet dependency caching in action.yml for faster builds - Comment out MSBuild SDK resolver and MSVC ARM64 tool steps in action.yml - Update stride-docs-test-build.yml to use windows-2025-vs2026 runner - Introduce action-backup.yml composite action for unified setup - Centralize .NET, repo checkout, and DocFX install steps - Add options to skip PDF or API building in the new action * docs: Update DocFX workflow, add release-candidate action - Comment out custom DocFX build/install in action.yml - Revert to installing DocFX 2.78.5 via dotnet tool update - Add action-release-candidate.yml composite action - New action sets up .NET, checks out Stride/DocFX, builds DocFX - Supports skipping PDF/API build, adds dependency caching and template build * feat: action.yml - Enable custom DocFX build workflow - Uncomment steps to checkout, build, and install DocFX from source - Use a specific branch of the DocFX repository for builds - Restore npm dependencies and build site templates - Add nightly NuGet source for dependencies - Comment out installation of prebuilt DocFX version 2.78.5 - Ensure workflow uses custom-built DocFX instead of release * chore: stride-docs-test-build.yml - Add permissions block - Add permissions block with contents: read to workflow file - No other changes to build job or configuration * feat: stride-docs-github.yml - Add stride-branch input, update runner - Add stride-branch input to allow branch selection (default 'master') - Change build runner to windows-2025-vs2026 - Pass stride-branch to setup-stride action - Update upload-pages-artifact to v5 * ci: Update workflows for new setup and config options - Add workflow_dispatch inputs for PDF/API skipping and branch selection - Switch build environment to windows-2025-vs2026 - Consolidate setup/checkout into custom setup-stride action - Remove legacy steps and manual DocFX install - Update artifact handling to upload built site directory - Improve CI configurability and maintainability * refactor: Remove Setup Stride composite action steps - Remove inputs and runs sections from action-backup.yml - Remove inputs and runs sections from action-release-candidate.yml - Eliminate reusable Setup Stride composite action and all related steps * docfx.json - Enforce restore and compilation checks - Set noRestore to false to enable package restore - Set allowCompilationErrors to false to require successful compilation * chore: docfx.json - Remove LangVersion: preview properties - Remove "LangVersion": "preview" from Stride.BepuPhysics and Stride.Physics project properties - Projects will no longer use C# preview features for docs generation
1 parent 2504f67 commit d0315d9

5 files changed

Lines changed: 180 additions & 178 deletions

File tree

‎.github/actions/setup-stride/action.yml‎

Lines changed: 103 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,10 @@ inputs:
1313
description: 'Skip API building when set to true'
1414
required: false
1515
default: 'false'
16+
stride-branch:
17+
description: 'Stride branch to checkout'
18+
required: false
19+
default: 'master'
1620

1721
runs:
1822
using: "composite"
@@ -23,6 +27,25 @@ runs:
2327
with:
2428
dotnet-version: 10.x
2529

30+
# - name: Configure MSBuild SDK resolver - Temporary
31+
# run: |
32+
# $dotnetRoot = Split-Path (Get-Command dotnet).Source -Parent
33+
# $sdkVersion = & dotnet --version
34+
# $msbuildSdksPath = Join-Path $dotnetRoot "sdk\$sdkVersion\Sdks"
35+
36+
# echo "DOTNET_ROOT=$dotnetRoot" >> $env:GITHUB_ENV
37+
# echo "MSBuildSDKsPath=$msbuildSdksPath" >> $env:GITHUB_ENV
38+
# echo "MSBuildEnableWorkloadResolver=false" >> $env:GITHUB_ENV
39+
40+
# Write-Host "DOTNET_ROOT=$dotnetRoot"
41+
# Write-Host "MSBuildSDKsPath=$msbuildSdksPath"
42+
# Write-Host "MSBuildEnableWorkloadResolver=false"
43+
44+
# if (-not (Test-Path $msbuildSdksPath)) {
45+
# throw "MSBuildSDKsPath does not exist: $msbuildSdksPath"
46+
# }
47+
# shell: pwsh
48+
2649
- name: Set Version in docfx.json
2750
run: |
2851
$settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
@@ -38,43 +61,90 @@ runs:
3861
token: ${{ inputs.github-token }}
3962
path: stride
4063
lfs: true
41-
ref: master
42-
43-
# Temporary solution till the new docfx is available
44-
# - name: Checkout DocFX
45-
# uses: actions/checkout@v6
46-
# with:
47-
# repository: dotnet/docfx
48-
# # Tested commit
49-
# ref: 917cda864650279e0bbe50b852cb98601e5efa4d
50-
# path: docfx-build
51-
# fetch-depth: 0
52-
53-
# - name: Restore npm dependencies
54-
# run: npm install
55-
# working-directory: docfx-build/templates
56-
57-
# - name: Build site templates
58-
# run: npm run build
59-
# working-directory: docfx-build/templates
60-
61-
# - name: Build DocFX from PR
62-
# run: dotnet pack src/docfx -c Release /p:Version=2.9-stride -o drop/nuget
63-
# working-directory: docfx-build
64-
# shell: pwsh
64+
ref: ${{ inputs.stride-branch }}
65+
66+
- name: Set up dependency caching for faster builds
67+
uses: actions/cache@v5
68+
with:
69+
path: ~/.nuget/packages
70+
key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', '**/*.props', '**/*.targets', '**/packages.lock.json', '**/NuGet.config') }}
71+
restore-keys: |
72+
${{ runner.os }}-nuget-
73+
74+
# Temporary solution till the new docfx is available with Analyzers update
75+
- name: Checkout DocFX
76+
uses: actions/checkout@v6
77+
with:
78+
repository: VaclavElias/docfx
79+
# Tested commit
80+
# ref: 917cda864650279e0bbe50b852cb98601e5efa4d
81+
# Use the temp-fix branch
82+
ref: refs/heads/temp-fix
83+
path: docfx-build
84+
fetch-depth: 0
85+
86+
- name: Restore npm dependencies
87+
run: npm install
88+
working-directory: docfx-build/templates
89+
shell: pwsh
90+
91+
- name: Build site templates
92+
run: npm run build
93+
working-directory: docfx-build/templates
94+
shell: pwsh
6595

66-
# - name: Build Install DocFX
67-
# run: dotnet tool install -g docfx --version 2.9-stride --add-source drop/nuget
68-
# working-directory: docfx-build
96+
- name: Add night build NuGet source
97+
run: |
98+
dotnet nuget add source "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet-tools/nuget/v3/index.json" --name dnceng-dotnet-tools --store-password-in-clear-text
99+
shell: pwsh
100+
101+
- name: Build DocFX from PR
102+
run: dotnet pack src/docfx -c Release /p:Version=2.9-stride -o drop/nuget
103+
working-directory: docfx-build
104+
shell: pwsh
105+
106+
# - name: Install MSVC ARM64/ARM64EC build tools - Temporary
107+
# run: |
108+
# $vswhere = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe"
109+
# $installer = "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vs_installer.exe"
110+
111+
# $installPath = & $vswhere -latest -products * -property installationPath
112+
113+
# if (-not $installPath) {
114+
# throw "Visual Studio installation not found."
115+
# }
116+
117+
# Write-Host "Visual Studio install path: $installPath"
118+
119+
# Start-Process -FilePath $installer -ArgumentList @(
120+
# "modify",
121+
# "--installPath", $installPath,
122+
# "--add", "Microsoft.VisualStudio.Component.VC.Tools.ARM64",
123+
# "--add", "Microsoft.VisualStudio.Component.VC.Tools.ARM64EC",
124+
# "--quiet",
125+
# "--norestart",
126+
# "--nocache",
127+
# "--wait"
128+
# ) -Wait -NoNewWindow
69129
# shell: pwsh
70-
# End of Temporary solution
71130

72-
- name: Install DocFX
73-
# This installs the latest version of DocFX and may introduce breaking changes
74-
# run: dotnet tool update -g docfx
75-
# This installs a specific, tested version of DocFX.
76-
run: dotnet tool update -g docfx --version 2.78.5
131+
- name: Build Install DocFX
132+
run: dotnet tool install -g docfx --version 2.9-stride --add-source drop/nuget
133+
working-directory: docfx-build
77134
shell: pwsh
135+
# End of Temporary solution
136+
137+
# - name: Install DocFX
138+
# # This installs the latest version of DocFX and may introduce breaking changes
139+
# # run: dotnet tool update -g docfx
140+
# # This installs a specific, tested version of DocFX.
141+
# run: dotnet tool update -g docfx --version 2.78.5
142+
# shell: pwsh
143+
144+
# - name: Prebuild Stride
145+
# run: dotnet build build\Stride.sln -c Release
146+
# working-directory: stride
147+
# shell: pwsh
78148

79149
- name: Build documentation
80150
run: |

‎.github/workflows/stride-docs-github.yml‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,10 @@ on:
1818
required: true
1919
default: true
2020
type: boolean
21+
stride-branch:
22+
description: 'Stride branch to checkout'
23+
required: false
24+
default: 'master'
2125

2226
permissions:
2327
contents: read
@@ -31,7 +35,7 @@ concurrency:
3135
jobs:
3236
build:
3337
name: Build documentation
34-
runs-on: windows-latest
38+
runs-on: windows-2025-vs2026
3539

3640
steps:
3741
- name: Checkout Stride Docs
@@ -47,9 +51,10 @@ jobs:
4751
github-token: ${{ secrets.GITHUB_TOKEN }}
4852
skip-pdf-building: ${{ inputs.skipPdfBuilding }}
4953
skip-api-building: ${{ inputs.skipApiBuilding }}
54+
stride-branch: ${{ inputs.strideBranch }}
5055

5156
- name: Upload Pages artifact
52-
uses: actions/upload-pages-artifact@v4
57+
uses: actions/upload-pages-artifact@v5
5358
with:
5459
path: ${{ env.DOCS_PATH }}/_site
5560

‎.github/workflows/stride-docs-staging-azure.yml‎

Lines changed: 33 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -20,102 +20,58 @@ on:
2020
- .gitignore
2121
- '.github/**'
2222
workflow_dispatch:
23+
inputs:
24+
skipPdfBuilding:
25+
description: Skip PDF building
26+
required: true
27+
default: true
28+
type: boolean
29+
skipApiBuilding:
30+
description: Skip API building
31+
required: true
32+
default: true
33+
type: boolean
34+
strideBranch:
35+
description: Stride branch to checkout
36+
required: true
37+
default: master
38+
type: string
39+
40+
permissions:
41+
contents: read
2342

2443
jobs:
2544
build:
2645
# Run this job only if the repository is 'stride3d/stride-docs'
2746
if: github.repository == 'stride3d/stride-docs'
28-
runs-on: windows-latest
47+
runs-on: windows-2025-vs2026
2948

3049
steps:
31-
- name: .NET SDK Setup
32-
uses: actions/setup-dotnet@v5
33-
with:
34-
dotnet-version: 10.x
35-
3650
# Checkout the Stride Docs repository from the branch that triggered the workflow
3751
- name: Checkout Stride Docs
3852
uses: actions/checkout@v6
3953
with:
4054
path: ${{ env.DOCS_PATH }}
4155
lfs: true
4256

43-
- name: Set Version in docfx.json
44-
run: |
45-
$settingsContent = Get-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Raw
46-
$updatedDocFxJsonContent = $settingsContent -replace '2.0.0.x', "${{ env.VERSION }}"
47-
Set-Content -Path "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}" -Value $updatedDocFxJsonContent
48-
shell: pwsh
49-
50-
# - name: Display Updated docfx.json
51-
# run: cat "${{ env.DOCS_PATH }}/${{ env.COMMON_SETTINGS_PATH }}"
52-
# shell: pwsh
53-
54-
# - name: Fail the Workflow
55-
# run: exit 1
56-
# shell: pwsh
57-
58-
# Checkout the Stride repository from the default branch
59-
- name: Checkout Stride (note the LFS)
60-
uses: actions/checkout@v6
57+
- name: Run Global Setup
58+
id: setup
59+
uses: ./stride-docs/.github/actions/setup-stride
6160
with:
62-
repository: stride3d/stride
63-
token: ${{ secrets.GITHUB_TOKEN }}
64-
path: stride
65-
lfs: true
66-
ref: master
67-
68-
# Temporary solution till the new docfx is available
69-
# - name: Checkout DocFX
70-
# uses: actions/checkout@v6
71-
# with:
72-
# repository: dotnet/docfx
73-
# # Tested commit
74-
# ref: 917cda864650279e0bbe50b852cb98601e5efa4d
75-
# path: docfx-build
76-
# fetch-depth: 0
77-
78-
# - name: Restore npm dependencies
79-
# run: npm install
80-
# working-directory: docfx-build/templates
81-
82-
# - name: Build site templates
83-
# run: npm run build
84-
# working-directory: docfx-build/templates
85-
86-
# - name: Build DocFX from PR
87-
# run: dotnet pack src/docfx -c Release /p:Version=2.9-stride -o drop/nuget
88-
# working-directory: docfx-build
89-
# shell: pwsh
90-
91-
# - name: Build Install DocFX
92-
# run: dotnet tool install -g docfx --version 2.9-stride --add-source drop/nuget
93-
# working-directory: docfx-build
94-
# shell: pwsh
95-
# End of Temporary solution
96-
97-
- name: Install DocFX
98-
# This installs the latest version of DocFX and may introduce breaking changes
99-
# run: dotnet tool update -g docfx
100-
# This installs a specific, tested version of DocFX.
101-
run: dotnet tool update -g docfx --version 2.78.5
102-
103-
- name: Build documentation
104-
run: ./build-all.bat
105-
working-directory: ${{ env.DOCS_PATH }}
106-
107-
- name: Compress artifact
108-
run: 7z a -r DocFX-app.zip ./${{ env.DOCS_PATH }}/_site/*
61+
github-token: ${{ secrets.GITHUB_TOKEN }}
62+
skip-pdf-building: ${{ inputs.skipPdfBuilding }}
63+
skip-api-building: ${{ inputs.skipApiBuilding }}
64+
stride-branch: ${{ inputs.strideBranch || 'master' }}
10965

11066
- name: Upload artifact for deployment job
111-
uses: actions/upload-artifact@v6
67+
uses: actions/upload-artifact@v7
11268
with:
11369
name: DocFX-app
114-
path: DocFX-app.zip
70+
path: ./${{ env.DOCS_PATH }}/_site
11571

11672
deploy:
11773
if: github.repository == 'stride3d/stride-docs'
118-
runs-on: windows-latest
74+
runs-on: windows-2025-vs2026
11975

12076
needs: build
12177
environment:
@@ -124,15 +80,10 @@ jobs:
12480

12581
steps:
12682
- name: Download artifact from build job
127-
uses: actions/download-artifact@v7
83+
uses: actions/download-artifact@v8
12884
with:
12985
name: DocFX-app
130-
131-
# - name: List current directory
132-
# run: ls
133-
134-
- name: Decompress artifact
135-
run: 7z x DocFX-app.zip "-o./${{ env.DOCS_PATH }}/_site"
86+
path: ./${{ env.DOCS_PATH }}/_site
13687

13788
- name: Deploy to Azure Web App
13889
id: deploy-to-webapp
@@ -141,4 +92,4 @@ jobs:
14192
app-name: 'stride-doc'
14293
slot-name: 'staging'
14394
publish-profile: ${{ secrets.AZUREAPPSERVICE_PUBLISHPROFILE_32FCD402B970463A9143B24C9B225749 }}
144-
package: ./${{ env.DOCS_PATH }}/_site
95+
package: ./${{ env.DOCS_PATH }}/_site

0 commit comments

Comments
 (0)