.NET 2.0 Documentation Generation with Sandcastle

I’ve been aware of Microsoft’s documentation generation system called Sandcastle for a while now but only recently have I had a chance to use it.

With NDoc all but dead (see NDoc 2.0 Alpha) Sandcastle is now one of very few free alternatives that I could find to generate documentation from my coding comments. However, it did take a bit of searching and playing around to get things working.

You need the following core applications:

• Microsoft Sandcastle
• Sandcastle Help File Builder

You may also need:

• HTML Help Workshop and Documentation

Once you’ve installed all three of these things you will need to ensure that each of your projects is creating XML Documents when then build. This can be done by viewing the properties of each of your projects in Visual Studio 2005 (right-click on the project and select “Properties”, select “Build” and ensure the “XML Documentation file” checkbox is checked.

Once you’ve ensured this checkbox is checked you’ll need to build your solution so the XML documents are generated.

Now open the Sandcastle Help File Builder application and you should be able to select Project -> New Project from Visual Studio Project…

Select and open up your Visual Studio solution and you should see the “Assemblies to Document” area filled with the project assemblies that belong to your solution. Now you need to populate the Build -> Dependencies section with all the dependencies of your projects. You can add full folders, single files or GAC dependencies using the buttons at the bottom of the “Documentation Assembly Dependencies” dialog.

Finally update the Paths -> HtmlHelp1xCompilerPath, Paths -> SandcastlePath and Paths -> OutputPath to the installation of the HTML Help Workshop location, Sandcastle location and your documentation output folder location respectively.

Click the build button or select Documentation -> Build Project and your documentation should eventually be build in your selected OutputPath.

Related posts:

1. Migrating ASP.NET Membership users from one database to another
2. Synaptics scrolling not working
3. How to make a cross domain web request with SilverLight 2