How to generate documentation using Sandcastle NuG

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.

Answer 1

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:

1. 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>
   

2. 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>
   

Answer 2

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.

Answer 3

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:

• Building Projects Outside the GUI
• Generating Documentation with Team Build