Update SHFB tools (#48)

* Updates

- update HelpFileBuilder
- Fix some errors and warnings after update
- improve ReadMe

* update shfb tools path

* Follow SHFB migration guide

After update there were some breaking changes. Files were updated accordingly  (see: https://ewsoftware.github.io/SHFB/html/bc933f8f-e792-45bf-afec-62aa2c46aa3b.htm)

* use older NET SDK

Since latest NET9 broke some NET8 features, try to use an older SDK

* Pin SDK via global.json

* correct NET version. the pinned didn't exist

* Using different sdks for different projects

* Set working directory for restoring workloads

Author: timunie

.github/workflows/deploy.yml

@@ -14,30 +14,42 @@ jobs:
       - uses: actions/checkout@v2
         with:
           submodules: true
+
+      - name: Install .NET 8 SDK
+        uses: actions/setup-dotnet@v3
+        with:
+          dotnet-version: '8.x'
+
       - uses: actions/setup-dotnet@v3
         with:
-          dotnet-version: '9.0.x'
+          dotnet-version: '9.x'
+
       - uses: actions/setup-node@v3
         with:
           node-version: 22.14
+
       - uses: pnpm/action-setup@v4
         with:
           version: 10.8.0
+
       - name: workloads 1
-        run: dotnet workload restore ext/Avalonia/src/iOS/Avalonia.iOS/Avalonia.iOS.csproj
+        working-directory: ./ext/Avalonia/src/
+        run: dotnet workload restore ./iOS/Avalonia.iOS/Avalonia.iOS.csproj
+
       - name: workloads 2
-        run: dotnet workload restore ext/Avalonia/src/Android/Avalonia.Android/Avalonia.Android.csproj
+        working-directory: ./ext/Avalonia/src/
+        run: dotnet workload restore ./Android/Avalonia.Android/Avalonia.Android.csproj
+
       - name: Run build script
         run: ./build.ps1 -pack
-      - name: find
-        shell: bash
-        run: find ./artifacts.zip
+
       - name: Upload SFHB result temporarily as atifact
         uses: actions/upload-artifact@v4
         with:
           name: website-artifact
           path: ./artifacts.zip
           retention-days: 1
+
   docusaurus_deploy_job:
     runs-on: ubuntu-latest
     name: Build website
@@ -48,20 +60,26 @@ jobs:
         with:
           name: website-artifact
           path: ./website/
+
       - uses: actions/setup-node@v3
         with:
           node-version: 22.14
+
       - uses: pnpm/action-setup@v4
         with:
           version: 10.8.0
+
       - name: Run build script
         working-directory: ./website/
         run: bash ./build.sh --build
+
       - name: Install dependencies
         run: sudo apt-get update; sudo apt-get install -y rsync
+
       - name: Setup key
         working-directory: ./website/
         run: echo '${{ secrets.DEPLOY_KEY }}' > ./upload.key && chmod 700 ./upload.key
+
       - name: Build And Deploy
         working-directory: ./website/
         run: ./deploy.sh ${{ vars.DEPLOY_HOST }} ${{ vars.DEPLOY_PORT }} ${{ vars.DEPLOY_USER }}

README.md

@@ -20,13 +20,20 @@ It is important to mind the build order.
 > .\build.ps1 -preview
 > ```
 
+## Updating the Sandcastle tools
+
+> [WARNING] if you update the SHFB-nuget packages you also need to update the tools path in `build.ps1`
+> ```ps1
+> # set SHFBRoot
+> $env:SHFBRoot = ".\src\packages\ewsoftware.shfb\2025.9.30\tools\"
+> ```
+
+
 ## Generate the API docs for newer Avalonia version
-Use the `set-version.ps1` script to update the version. 
+Use the `update-submodule.ps1` script to update the version to the latest stable. if you need any other branch version, you need to link the branch name for the submodule by hand. 
 
-```ps1
-# -version: specify the Avalonia version to document. If this parameter is not set, `AvaloniaVersion.txt` will be used instead. 
-.\set-version.ps1 11.2.0 
-```
+> [!NOTE]
+> The file `./ext/Avalonia/build/SharedVersion.props` stores the current version info. 
 
 > [!WARNING]
 > Remember to commit all updates made to the submodule. 

build.ps1

@@ -20,7 +20,7 @@ New-item ./website/AvaloniaVersion.txt -ItemType File -Value  $version -Force
 Write-Host "Avalonia version is $version"
 
 # set SHFBRoot
-$env:SHFBRoot = ".\src\packages\ewsoftware.shfb\2025.3.22\tools\"
+$env:SHFBRoot = ".\src\packages\ewsoftware.shfb\2025.9.30\tools\"
 
 # Define a list of dotNET projects to build
 $projectsToBuild = @(
@@ -69,24 +69,49 @@ $projectsToBuild = @(
 	"src/ApiDocumentation/ApiDocumentation.shfbproj"
 )
 
-foreach ($proj in $projectsToBuild){
-	dotnet build $proj -c Release
-	Write-Host "`n built $proj" -ForegroundColor DarkGreen -BackgroundColor Gray
-	Write-Host "`n"
+foreach ($proj in $projectsToBuild)
+{
+    # Ensure dotnet resolves global.json relative to the project by changing into the project's directory
+    $projDir = Split-Path $proj -Parent
+    $projFile = Split-Path $proj -Leaf
+
+    if (-not [string]::IsNullOrEmpty($projDir))
+    {
+        Push-Location $projDir
+        try
+        {
+            Write-Host "Building $projFile in directory $( Get-Location )..."
+            dotnet build ".\$projFile" -c Release
+        }
+        finally
+        {
+            Pop-Location
+        }
+    }
+    else
+    {
+        # project is in repository root
+        Write-Information "Building $projFile in repository root..."
+        dotnet build ".\$projFile" -c Release
+    }
+
+    Write-Information "`n built $projFile"
+    Write-Information "`n"
 }
 
+
 # preview the website if preview switch is on
 if($preview.IsPresent){
-	pushd ./website
+	Push-Location ./website
 	./build.ps1 -preview
-	popd
+	Pop-Location
 }
 
 # build the website if build switch is on
 if($build.IsPresent){
-	pushd ./website
+	Push-Location ./website
     ./build.ps1 -build
-	popd
+	Pop-Location
 }
 
 # pack the md-files and version settings if pack switch is on

global.json

@@ -0,0 +1,5 @@
+{
+  "sdk": {
+    "version": "9.*"
+  }
+}

src/ApiDocumentation/ApiDocumentation.shfbproj

@@ -135,8 +135,8 @@
 	<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|Win32' " />
 	<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|Win32' " />
 	<ItemGroup>
-		<PackageReference Include="EWSoftware.SHFB" Version="2025.03.22"/>
-		<PackageReference Include="EWSoftware.SHFB.NET" Version="9.0.0"/>
+		<PackageReference Include="EWSoftware.SHFB" Version="2025.9.30" />
+		<PackageReference Include="EWSoftware.SHFB.NET" Version="10.0.0" />
 	</ItemGroup>
 	<!-- Import the common build targets during NuGet restore because before the packages are being installed, $(SHFBROOT) is not set yet -->
 	<Import Project="$(MSBuildToolsPath)\Microsoft.Common.targets" Condition="'$(MSBuildRestoreSessionId)' != ''"/>

src/AvaloniaAttributesPlugin/AvaloniaAttributesPlugIn.cs

@@ -1,12 +1,12 @@
-using SandcastleBuilder.Utils.BuildComponent;
-using SandcastleBuilder.Utils.BuildEngine;
 using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
 using System.Text.RegularExpressions;
 using System.Xml.Linq;
 using System.Xml.XPath;
+using Sandcastle.Core.BuildEngine;
+using Sandcastle.Core.PlugIn;
 
 namespace AvaloniaAttributes
 {
@@ -36,7 +36,7 @@ public sealed class AvaloniaAttributesPlugIn : IPlugIn
 
         private List<ExecutionPoint>? _executionPoints;
 
-        private BuildProcess? _builder;
+        private IBuildProcess? _builder;
 
         //=====================================================================
 
@@ -61,7 +61,7 @@ public IEnumerable<ExecutionPoint> ExecutionPoints
         /// </summary>
         /// <param name="buildProcess">A reference to the current build process</param>
         /// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
-        public void Initialize(BuildProcess buildProcess, XElement configuration)
+        public void Initialize(IBuildProcess buildProcess, XElement configuration)
         {
             _builder = buildProcess;
 

src/AvaloniaAttributesPlugin/AvaloniaAttributesPlugIn.csproj

@@ -62,9 +62,8 @@
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="System.ComponentModel.Composition" Version="9.0.3" />
-		<PackageReference Include="EWSoftware.Sandcastle.Core" Version="2025.3.22" />
-		<PackageReference Include="EWSoftware.SandcastleBuilder.Utils" Version="2025.3.22" />
+		<PackageReference Include="System.ComponentModel.Composition" Version="9.0.10" />
+		<PackageReference Include="EWSoftware.Sandcastle.Core" Version="2025.9.30" />
 	</ItemGroup>
 
 	<!-- TODO: If you have a project with configuration forms, you can include it in this package by

src/DocusaurusExportPlugin/DocusaurusContentGenerator.cs

@@ -24,7 +24,7 @@
 using System.Xml;
 using System.Xml.Linq;
 using DocusaurusExportPlugin.Sidebar;
-using SandcastleBuilder.Utils.BuildEngine;
+using Sandcastle.Core.BuildEngine;
 
 namespace DocusaurusExportPlugin
 {
@@ -40,7 +40,7 @@ public class DocusaurusContentGenerator
 
         private static readonly MatchEvaluator MeDecodeEntities = m => WebUtility.HtmlDecode(m.Value);
 
-        private readonly BuildProcess _buildProcess;
+        private readonly IBuildProcess _buildProcess;
         private readonly string _workingFolder;
 
         //=====================================================================
@@ -49,7 +49,7 @@ public class DocusaurusContentGenerator
         /// Constructor
         /// </summary>
         /// <param name="buildProcess">The build process to use</param>
-        public DocusaurusContentGenerator(BuildProcess buildProcess)
+        public DocusaurusContentGenerator(IBuildProcess buildProcess)
         {
             _buildProcess = buildProcess ?? throw new ArgumentNullException(nameof(buildProcess));
 

…rtPlugin/DocusaurusExportPluginPlugIn.cs …usExportPlugin/DocusaurusExportPlugIn.cssrc/DocusaurusExportPlugin/DocusaurusExportPluginPlugIn.cs renamed to src/DocusaurusExportPlugin/DocusaurusExportPlugIn.cs src/DocusaurusExportPlugin/DocusaurusExportPluginPlugIn.cs renamed to src/DocusaurusExportPlugin/DocusaurusExportPlugIn.cs

@@ -4,9 +4,8 @@
 using System.Linq;
 using System.Text.Json;
 using System.Xml.Linq;
-
-using SandcastleBuilder.Utils.BuildComponent;
-using SandcastleBuilder.Utils.BuildEngine;
+using Sandcastle.Core.BuildEngine;
+using Sandcastle.Core.PlugIn;
 
 namespace DocusaurusExportPlugin
 {
@@ -30,13 +29,13 @@ namespace DocusaurusExportPlugin
     /// dispose of them when the container is disposed of.</remarks>
     [HelpFileBuilderPlugInExport("DocusaurusExport", Version = AssemblyInfo.ProductVersion,
       Copyright = AssemblyInfo.Copyright, Description = "DocusaurusExport plug-in")]
-    public sealed class DocusaurusExportPluginPlugIn : IPlugIn
+    public sealed class DocusaurusExportPlugIn : IPlugIn
     {
         //=====================================================================
 
         private List<ExecutionPoint>? _executionPoints;
 
-        private BuildProcess? _builder;
+        private IBuildProcess? _builder;
 
         /// <summary>
         /// Gets a dictionary with the mapping between the AssemblyName and the nuget package
@@ -68,7 +67,7 @@ public IEnumerable<ExecutionPoint> ExecutionPoints
         /// </summary>
         /// <param name="buildProcess">A reference to the current build process</param>
         /// <param name="configuration">The configuration data that the plug-in should use to initialize itself</param>
-        public void Initialize(BuildProcess buildProcess, XElement configuration)
+        public void Initialize(IBuildProcess buildProcess, XElement configuration)
         {
             _builder = buildProcess;
 
@@ -101,7 +100,7 @@ public void Execute(ExecutionContext context)
         /// This handles garbage collection to ensure proper disposal of the plug-in if not done explicitly
         /// with <see cref="Dispose()"/>.
         /// </summary>
-        ~DocusaurusExportPluginPlugIn()
+        ~DocusaurusExportPlugIn()
         {
             this.Dispose();
         }

src/DocusaurusExportPlugin/DocusaurusExportPlugin.csproj

@@ -63,9 +63,9 @@
 	</ItemGroup>
 
 	<ItemGroup>
-		<PackageReference Include="System.ComponentModel.Composition" Version="9.0.3" />
-		<PackageReference Include="EWSoftware.Sandcastle.Core" Version="2025.3.22" />
-		<PackageReference Include="EWSoftware.SandcastleBuilder.Utils" Version="2025.3.22" />
+		<PackageReference Include="System.ComponentModel.Composition" Version="9.0.10" />
+		<PackageReference Include="System.Text.Json" Version="9.0.10" />
+		<PackageReference Include="EWSoftware.Sandcastle.Core" Version="2025.9.30" />
 	</ItemGroup>
 
 	<!-- TODO: If you have a project with configuration forms, you can include it in this package by