Sandcastle

Here’s another brain dump on how to get started with Sandcastle.

1. Install the latest release of Sandcastle (currently the June 2010 release) from
   http://sandcastle.codeplex.com/
2. Install the latest release of Sandcastle Help File Builder (currently the Jul 2010 release) from
   http://shfb.codeplex.com/
3. Make sure your Visual Studio projects that contains the things you want to document has the XML documentation file checkbox enabled under Project properties->Build->Output->XML documentation file.
4. Create a new SHFB-project and add the assemblies you want to create documentation for as ‘Documentation Sources’. 
   
   I tried adding the .proj file for the project (*.Service.Contracts) holding references to two other projects (*.Service.Messages and *.Entities), but then the generated documentation were missing information on the types defined in the referenced projects. 
5. Set the project properties you find relevant. The SHFB supports the standard Sandcastle styles (Hana, VS2005 and Prototype).
   I personally prefer the Hana-style.
   
6. Documentation can be created either by using the SHFB GUI (Documentation->Build project) or via MSBuild.
   Currently SHFB creates a .build file targeting MSBuild 3.5, so if you run the .build file through MSBuild 4.0 you will get a warning saying:

   SHFB : warning BHT0001: Unable to get executing project: Unable to obtain int
   ernal reference.  The specified project will be loaded but command line propert
   y overrides will be ignored

7. Fair enough if you stick with keeping configuration inside .build file and avoid command line properties.
   Until SHFB supports MSBuild 4.0 there are workarounds, see the comments in this thread for inspiration:
   http://shfb.codeplex.com/Thread/View.aspx?ThreadId=50652

NOTE 1: If you get an error when using MSBuild saying that the SandcastleHelpFileBuilder.targets file can’t be found, add an environment variable named SHFBROOT and set the value to c:\[path to your SHFB installationfolder], eg.: C:\Program Files (x86)\Sandcastle Help File Builder

NOTE 2: Seems like DocProject is working on adding support for the latest Sandcastle/VS release. Might be an alternative to SHFB once it’s been released.