Add Sandcastle Help File Builder to your Github Workflow

[StephenHidem]

Introduction

I have been collaborating with Eric Woodruff on integrating SHFB into a Github workflow. This discussion focuses on building a website and deploying it to Github Pages. The Sandcastle tools are packaged as a NuGet package and referenced in your .shfbproj project file.

Known issues and updates are listed at the end of discussion.

The NuGet Packages

You need to add the tools package and a reflection data set package to your Sandcastle project. The packages are located at NuGet.org.

EWSoftware.SHFB, version 2025.12.18, is the Sandcastle tools package.

You must install one or more of the Reflection Data Set packages based on which platform types you need:
.NET, .NETFramework, .NETCore, .NETMicroFramework, .NETPortable, Silverlight, WindowsPhone, WindowsPhoneApp, and/or UniversalWindows.

If multiple versions are available for any given reflection data set package, install the latest version as it will cover all prior versions as well.

Your Sandcastle Project File

You can add the NuGet packages to your Sandcastle project by right clicking on the Component Packages node and selecting

Manage NuGet Packages ...

Alternatively, it's a simple matter to directly edit the .shfbproj file and add the package references -

  <ItemGroup>
    <PackageReference Include="EWSoftware.SHFB">
      <Version>2025.12.18</Version>
    </PackageReference>
    <PackageReference Include="EWSoftware.SHFB.NET">
      <Version>10.0.0</Version>
    </PackageReference>
  </ItemGroup>

Example Github Workflow

Here is an example workflow that I use to build, test, and deploy my NuGet packages and website built with Sandcastle -

# This workflow will build a .NET project
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net

name: Deploy Release to NuGet and Website

on:
  release:
    types:
      - published
  workflow_dispatch:
    
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      actions: read

    steps:
    - uses: actions/checkout@v4
    - name: Setup .NET
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: 10.0.x

    # Restore Dependencies
    - name: Restore Dependencies
      run: |
        dotnet restore AntPlus
        dotnet restore AntRadioInterface
        dotnet restore AntPlus.Extensions.Hosting
        dotnet restore AntPlus.UnitTests
        dotnet restore Examples/AntUsbStick
        dotnet restore Extensions/Hosting/Hosting.UnitTests
        dotnet restore Documentation/Documentation.shfbproj

    # Build Github Solution Configuration
    - name: Build NuGet Packages
      run: dotnet build --no-restore --configuration Github

    # Run Unit Tests
    - name: Run Unit Tests
      run: dotnet test --no-build --verbosity minimal --configuration Github

    # Publish NuGet Packages
    - name: Publish NuGet Packages
      run: dotnet nuget push **/*.nupkg --source https://api.nuget.org/v3/index.json --api-key ${{ secrets.NUGET_API_KEY }} --skip-duplicate

    # Build Documentation and Upload Artifacts
    - name: Build Documentation
      run: dotnet build Documentation/Documentation.shfbproj --no-restore --configuration Release
    - name: Setup Pages
      uses: actions/configure-pages@v5
    - name: Upload artifact
      uses: actions/upload-pages-artifact@v3
      with:
        path: './Documentation/Help'

  deploy:
    needs: build

    # Grant permissions to deploy to GitHub Pages
    permissions:
      pages: write
      id-token: write

    # Deploy to GitHub Pages environment
    environment:
        name: github-pages
        url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
    # Deploy Documentation to GitHub Pages
    - name: Deploy to GitHub Pages
      id: deployment
      uses: actions/deploy-pages@v4

Some things I want to point out -

• My example uses the Github hosted runner ubuntu-latest. You could use the windows-latest runner, but you pay a 2x multiplier on the time used.
• You should restore the dependencies and then build the projects you are documenting with the --no-restore option.
• You can retrieve the LastBuild.log file by downloading the artifacts file generated and extracting the compressed files.

Conclusion

I have not tested all the potential scenarios, but I believe it is feature complete. Your feedback is greatly appreciated so we can correct any issues that arise prior to an official release. Post your issues here or in Issues.

Hope you find this useful and best regards, Stephen Hidem.

Known Issues and Updates

Updates

• 11/7/2025: SmallEarthTech.SHFB-alpha.1 update has been released to NuGet. Fixes issue with the OutputPath directory separators.
• 11/21/2025: SmallEarthTech.SHFB, version 2025.11.21-alpha has been released to NuGet. The package incorporates updates to the tools. Notably, the AlwaysLoadProject property is no longer needed. This is reflected in the YAML workflow.
• 12/19/2025: EWSoftware.SHFB, version 2025.12.18 has been released to NuGet. This is the official release and the SmallEarthTech.SHFB are deprecated and unlisted on NuGet.

[raczeja]

Stephen thanks for work on this,
I found an issue, I'm using Additional Reference Links https://github.com/Accenture/Ocaramba/blob/master/Ocaramba.Documentation/Ocaramba.Documentation.shfbproj
<PlugInConfigurations> <PlugInConfig id="Additional Reference Links" enabled="True"> <configuration> <targets> <target htmlSdkLinkType="None" helpViewerSdkLinkType="Id" websiteSdkLinkType="None" helpFileProject="Selenium.shfbproj" /> </targets> </configuration> </PlugInConfig> </PlugInConfigurations>

and getting an error while budling documentation

<plugIn name="Additional Reference Links" behavior="Before" priority="1000"> Performing partial builds on additional targets&#39; projects Building D:\a\Ocaramba\Ocaramba\Ocaramba.Documentation\Selenium.shfbproj Initializing Failed </plugIn> Last step completed in 00:00:00.0456 </buildStep> <buildStep step="Failed"> SHFB: Error BE0029: Unexpected error while executing plug-in &#39;Additional Reference Links&#39;: Sandcastle.Core.BuildEngine.BuilderException: Unable to build additional target project: D:\a\Ocaramba\Ocaramba\Ocaramba.Documentation\Selenium.shfbproj at SandcastleBuilder.PlugIns.AdditionalReferenceLinksPlugIn.Execute(ExecutionContext context) in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderPlugIns\AdditionalReferenceLinksPlugIn.cs:line 143 at SandcastleBuilder.MSBuild.BuildEngine.BuildProcess.ExecutePlugIns(ExecutionBehaviors behavior) in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildEngine\BuildProcess.PlugIns.cs:line 179 at SandcastleBuilder.MSBuild.BuildEngine.BuildProcess.ExecutePlugIns(ExecutionBehaviors behavior) in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildEngine\BuildProcess.PlugIns.cs:line 187 at SandcastleBuilder.MSBuild.BuildEngine.BuildProcess.GenerateNamespaceSummaries() in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildEngine\BuildProcess.Namespaces.cs:line 105 at SandcastleBuilder.MSBuild.BuildEngine.BuildProcess.Build() in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildEngine\BuildProcess.cs:line 1053 Unable to build additional target project: D:\a\Ocaramba\Ocaramba\Ocaramba.Documentation\Selenium.shfbproj at SandcastleBuilder.PlugIns.AdditionalReferenceLinksPlugIn.Execute(ExecutionContext context) in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderPlugIns\AdditionalReferenceLinksPlugIn.cs:line 143 at SandcastleBuilder.MSBuild.BuildEngine.BuildProcess.ExecutePlugIns(ExecutionBehaviors behavior) in C:\Users\Steph\source\repos\StephenHidem\SHFB\SHFB\Source\SandcastleBuilderMSBuild\BuildEngine\BuildProcess.PlugIns.cs:line 179 </buildStep> </shfbBuild>

I workaround it by changing to
<PlugInConfigurations> <PlugInConfig id="Assembly Binding Redirection" enabled="True"> <configuration useGAC="false"> <assemblyBinding /> <ignoreIfUnresolved> <assemblyIdentity name="Selenium.Support" /> <assemblyIdentity name="Selenium.WebDriver" /> </ignoreIfUnresolved> </configuration> </PlugInConfig> </PlugInConfigurations> </PropertyGroup>

and now i'm getting many warnings
SHFB : warning BE0066: ResolveReferenceLinksComponent: [P:Ocaramba.DriverContext.Driver] Unknown reference link target 'T:OpenQA.Selenium.IWebDriver'. [D:\a\Ocaramba\Ocaramba\Ocaramba.Documentation\Ocaramba.Documentation.shfbproj]

[StephenHidem]

Hi Jakub,
Thank you for the feedback. I'll look into it and get back to you.

[StephenHidem]

@raczeja I cloned your project and experimented with building locally on my PC. I think these steps may help in your case -

1. I disabled the "Assembly Binding Redirection" plug-in and added back the "Additional Reference Links" plug-in with your configuration to the Ocaramba.Documentation.shfbproj Sandcastle project file.
2. I see in your workflow that it uses the windows-latest runner to build the documentation. That allows use of msbuild. You'll need to setup and configure msbuild in your workflow, adding setup-msbuild. Check the Github docs and the Github repo that contains setup-msbuild.
3. In your workflow, replace
   run: dotnet build Ocaramba.Documentation/Ocaramba.Documentation.shfbproj --no-restore --configuration ${{ env.buildConfiguration }} -p:AlwaysLoadProject=true
   with
   run: msbuild Ocaramba.Documentation/Ocaramba.Documentation.shfbproj -t:Build -p:RestorePackages=false -p:configuration=${{ env.buildConfiguration }} -p:AlwaysLoadProject=True

This should allow your workflow to execute without all the BE0066 warnings. You will get a BHT0001 warning which is expected. I also noticed that permissions were not set in the deploy step. I don't know if that was intentional or not, but the deploy will fail.

[raczeja]

thank you

[EWSoftware]

A help topic has been added: https://ewsoftware.github.io/SHFB/html/GitHubWorkflow.htm

[StephenHidem]

The acknowledgement is deeply appreciated!