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