How to generate documentation using Sandcastle NuGet package (EWSoftware.SHFB)?

Question

I am trying to generate website documentation for my C# code using the NuGet package of Sandcastle in Visual Studio (EWSoftware.SHFB). The fact is that I don't know how to use it. I install it from the NuGet package manager and then I have no idea what to do with it.

I have no problem to edit my documentation project and to generate the corresponding website using the VS Sandcaslte extension installed with the default installer.

Thank you for your help.

This might also be helpful. https://www.codeproject.com/Articles/82430/Authoring-Integrating-API-Help-for-VS-and-VS — dviljoen, Dec 08 '16 at 14:04

score 6 · Answer 1 · answered Nov 12 '15 at 09:49

6

Assuming that you already have a solution with a project, add a new project of type 'Documentation' to your solution.

Right-click Documentation Sources and add a source by selecting the csproj you wish to document.

Then just build.

answered Nov 12 '15 at 09:49

Frank Rem

3,632
2
25
37

1

I want users that don't have the Sandcatle component installed to be able to generate the documentation. – Numid Nov 12 '15 at 09:52
What software would generate that documentation in that scenario? – Frank Rem Nov 12 '15 at 09:53
As stated at https://github.com/EWSoftware/SHFB/blob/master/NuGet/ReadMe.txt, the NuGet package should provide such a functionnality. – Numid Nov 12 '15 at 09:58
I could be wrong because I never did this, but as I understand from the readme, the NuGet package provides the same functionality (referred to as Sandcastle Help File Builder), but it is installed through NuGet instead of running sandcastle.msi. – Frank Rem Nov 12 '15 at 10:16
I have uninstalled Sandcastle from the Windows Uninstaller, I have uninstalled the VS Sandcastle extension from VS and I have downloaded the NuGet package from VS. The behaviour is not the same... – Numid Nov 12 '15 at 10:20
What is the difference? – Frank Rem Nov 12 '15 at 10:33
Thre is no way to create/edit/build SHFB project from the VS GUI. However there is a Sandcastle installation in the NuGet packages folder of the solution. I might have to run special commands as post-build events of a project. – Numid Nov 12 '15 at 10:38

score 5 · Accepted Answer · answered Nov 13 '15 at 10:11

MsBuild.exe MyDocumentationProject.shfbproj generated the documentation. It means that the project can not be edited via VS, but it can be generated using the command line.

Beforhand, as stated at https://github.com/EWSoftware/SHFB/blob/master/NuGet/ReadMe.txt:

the ComponentPath property must be set in MyDocumentationProject.shfbproj to provide reflection information regarding the framework you are using.
```
<PropertyGroup>
  <ComponentPath>$(MSBuildThisFileDirectory)..\packages\EWSoftware.SHFB.NETFramework.4.6</ComponentPath>
</PropertyGroup>
```

The SHFB environment variable must be set conditionally in MyDocumentationProject.shfbproj.

<PropertyGroup>
  <SHFBROOT Condition=" '$(SHFBROOT)' == '' ">$(MSBuildThisFileDirectory)..\packages\EWSoftware.SHFB.2015.10.10.0\Tools\</SHFBROOT>
</PropertyGroup>

How is the project built after adding these properties? I have a .NET library project where I included these EWSoftware.SHFB nuget packages, but no help files are generated when I build this project. — Sumit Jain, May 28 '19 at 11:17
Just have same issue, but the problem was in duplicate , do not forget to delete it. — Vlad, Jan 18 '21 at 15:15

score 1 · Answer 3 · answered Dec 08 '16 at 13:20

I created the documentation project with the Visual Studio plug-in after installing Sandcastle.

I added the following post-build event on another project when completed successfully:

IF "$(ConfigurationName)"=="Debug" Goto Exit

ECHO Building SHFB help file via MSBuild
"$(SystemRoot)\Microsoft.NET\Framework\v4.0.30319\MSBuild.exe"  /p:CleanIntermediates=True /p:Configuration=Release "$(SolutionDir)Documentation\Documentation.shfbproj"

:Exit

The SHFB environment variable in the project documentation file looks like this:

<!-- NOTE: Update the version number in the path (YYYY.M.D.R) to match the package version -->
<SHFBROOT Condition=" '$(SHFBROOT)' == '' ">$(MSBuildThisFileDirectory)..\packages\EWSoftware.SHFB.2016.9.17.0\tools\</SHFBROOT>

If Sandcastle isn't installed on the system, it'll use the executables from the NuGet package. Make sure the version matches for others.

These documentation links might help for issues I forgot about:

How to generate documentation using Sandcastle NuGet package (EWSoftware.SHFB)?

3 Answers3

Linked