Feature Request: SHFB builder for Github Actions / Workflow

[scegg]

Please consider to write a Github Action to build SHFB project in order to complete the CI/CD. Thanks.

[EWSoftware]

I don't know anything about GitHub actions or workflows. I'll have to learn about them first to see if it's even possible to run SHFB in one of them. That will take some time. If anyone has done this already and is willing to share, please feel free to do so.

[scegg]

doc: https://docs.github.com/en/actions/creating-actions basically, there is very possible if SHFB:

• has a command line based compiler,
• accept a folder or a project file as input,
• generate output to current or a folder specified, and
• can be run under ubuntu.

[EWSoftware]

There may be a potential issue. SHFB is full .NET Framework and as far as I know only runs on Windows. I do have plans to look into a .NET Core version but that's a ways off for now.

[scegg]

Hmm, wait for you to switch for core version 1st.

BTW, it should not be a good idea to include any code in the main structure, which can only use under Windows.

[EWSoftware]

Yes, I've started evaluating it. I need to shift some stuff around to isolate the UI stuff like component configuration forms and how they are invoked. For the most part, it compiles cleanly once those bits are removed. The build tasks also need to be set up for multi-targeting as the MSBuild versions used are different.

So, in the meantime, I'll leave this open for future consideration.

[scegg]

IMHO, the current VS is not built on netcore. Maybe the key jobs are how to build a off-the-vs compiler interface and make sure the data structures are compatible between the VS-IDE components and compiler.

Another reason that not suggest to change the VS-IDE components is, I guess the VS will have a big change to suite dotnet core very soon in order to support linux, macos and arm based hardwares.

[ritchiecarroll]

Here's an example of one I got operational on .NET Framework: https://github.com/GridProtectionAlliance/SIEGate/blob/master/.github/workflows/codeql-analysis.yml

Took a little too much work to learn how things work, IMO, but I was finally able to get it to go and produce some feedback. They need some better reference examples for various platforms.

Hopefully what I learned for the script above will be helpful to you.

[Bassman2]

Hi all,

I wrote a github action for SHFB. You can use it with:

- name: Install SHFB
   uses: Bassman2/setup-SHFB@v1
   with:
     version: v2021.4.9.0

There is currently only one known problem, the vsix installation takes 8 min.

My plan is to give it to Eric if it is ready.

Feel free to test it.

Ralf

[EWSoftware]

@Bassman2 Is that the same thing as what's being requested here? I wouldn't think the VSIX has any place in a GitHub action so why would it need to be installed?

Progress has been made with regard to the original issue as the next release supports running under .NET Core. Ubuntu support is still questionable though as I'm quite sure there are issues with path separators throughout the code base so those still need to be addressed.

[Bassman2]

OK I should have read more than the headline. My Github Action downloads SHFB and installs it so that solutions can be built with SHFB projects.

[Shane32]

I'm looking forward to this feature as well.

In the meantime, I forked @Bassman2 's GitHub Action workflow to work with the latest version here. I have it running within a Windows runner to ignore any compatibility issue with Linux. Unfortunately it takes as much as 20 minutes to install the vsix, but it does install and run.

On a side note, it does not build the documentation with dotnet build, either in the GitHub Action workflow or locally on my development computer; it hits a null reference exception and I still need to use msbuild. Let me know if I should post details on this.

@EWSoftware Let me know if/how I can help with this feature.

[EWSoftware]

@Shane32 If the null reference exception you are referring to is #930, install v2022.8.14.1 which should resolve the issue. Note that you must manually uninstall v2022.8.14.0 first though as it isn't being removed by the latest MSI installer for some reason. If installed side by side, the issue can still occur.

I'm not sure what the workflow does as I haven't look at it yet, but if there's a way to skip the VSIX install, I'd just remove that part as it isn't needed for command line builds, just the MSI installer.

dotnet build still works as far as I know and does with a test case I just tried. Are you getting any particular error when doing so?

[Shane32]

I just installed SHFB for the first time today (as version 2022.8.14.1), so it can't be a conflict with an old version.

I will try modifying the GitHub Action workflow to exclude the vsix install and see how that goes.

Here's the dotnet build output:

MSBuild version 17.3.0+92e077650 for .NET
  Determining projects to restore...
  Nothing to do. None of the projects specified contain packages to restore.
  Building C:\Users\Shane\source\repos\rimland\EPPlus\Doc\EPPlusDoc.shfbproj
  Initializing
  ValidatingDocumentationSources
SHFB : warning BE0007: A project with a different or higher framework version was found.  Changing project FrameworkVersion property from 'Cross-platform (.NE
T Core/.NET Standard)' to '.NET Core/.NET Standard/.NET 5.0+' for the build. [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\EPPlusDoc.shfbproj]
SHFB : warning BE0062: No documentation source XML comments files found.  The help file will not contain any member comments. [C:\Users\Shane\source\repos\rim
land\EPPlus\Doc\EPPlusDoc.shfbproj]
  GenerateSharedContent
  GenerateApiFilter
  GenerateReflectionInfo
SHFB : error BE0043: Unexpected error detected in last build step.  See build log for details. [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\EPPlusDoc.shfbp
roj]
  Failed
  Build details can be found in C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\LastBuild.log

Build FAILED.

Here's the relevant part of the build log:

       GenerateRefInfo:
         Microsoft.Build (v17.3.0+92e0776509a23ed2c1e24bf906a92f045899b885)
         c Microsoft Corporation. All rights reserved.
         No source code context base path specified.  Source context information is unavailable.
         Loaded 1 assemblies for reflection and 126 dependency assemblies.
     1>MRefBuilder : error : An unexpected error occurred trying to execute the MRefBuilder MSBuild task: System.NullReferenceException: Object reference not set to an instance of an object. [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.WriteParameter(Parameter parameter) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.WriteParameters(ParameterList parameters) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.WriteMember(Member member, TypeNode type, Boolean includeSourceCodeContext) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.WriteMember(Member member, Boolean includeSourceContext) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.VisitMember(Member member) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitMembers(MemberList members) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitType(TypeNode type) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.VisitType(TypeNode type) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitTypes(TypeNodeList types) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitNamespace(Namespace space) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.VisitNamespace(Namespace space) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitNamespaces(NamespaceList spaces) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.ManagedReflectionWriter.VisitNamespaces(NamespaceList spaces) [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.Reflection.ApiVisitor.VisitApis() [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.MSBuild.MRefBuilder.GenerateReflectionInformation() [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
MRefBuilder : error :    at Sandcastle.Tools.MSBuild.MRefBuilder.Execute() [C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj]
     1>Done Building Project "C:\Users\Shane\source\repos\rimland\EPPlus\Doc\Help\Working\GenerateRefInfo-eb950e69-b6cb-4919-ad56-8549a3ec935c.proj" (default targets) -- FAILED.
    Last step completed in 00:00:01.0976

If you want to play with it yourself, just download my fork of EPPlus 4.5.3.3 here: https://github.com/Shane32/EPPlus.git

Then do this:

• In the root folder of the repo, dotnet build -c Release
• In the Doc folder, dotnet build -c Release -- which fails as shown above

However, if you try this, all is well:

• In the Doc folder, "C:\program files\microsoft visual studio\2022\professional\msbuild\current\bin\amd64\msbuild" EPPlusDoc.sln -t:rebuild -verbosity:minimal -property:Configuration=Release

[Shane32]

I would like to comment and say that I have been looking for a good tool to generate API documentation, and I look forward to trying out this tool on other of my projects. 👍 👍 👍

[Shane32]

By the way, here's a direct link to view the shfbproj file:

• https://github.com/Shane32/EPPlus/blob/master/Doc/EPPlusDoc.shfbproj

I didn't write it, but it seems to work well (with msbuild).

[Shane32]

I will try modifying the GitHub Action workflow to exclude the vsix install and see how that goes.

The GitHub Action workflow builds the documentation project just fine without the vsix installation, and the msi only takes 15 seconds to install. 👍 (Again, this is on a Windows runner.)

[Zastai]

If you're using references to up to date nuget packages for EWSoftware.SHFB + whatever framework reference you need (e.g. EWSoftware.SHFB), a help project should build just fine using a plain dotnet build, so should also work in a GH Action where you have used setup-dotnet to set up a .NET SDK.