Free Documentation Tool: Sandcastle
In my recent
review of Document! X 2011, a tool for generating MSDN-style documentation for your projects by scanning your assemblies, a reader pointed out that you can achieve many of the same results by using Ghost Doc and Sandcastle. I've discussed
Ghost Doc (a free tool for generating XML comments in your source code) before. Both Document! X and Sandcastle will incorporate your XML comments into the documentation they generate through scanning your assemblies.
Sandcastle is a set of command-line utilities that's free from Microsoft. Sandcastle generates the inputs to Microsoft's various Help compilers, which you'll also need to install. In addition, using Sandcastle would be painful were it not for a free GUI, the Sandcastle Help File Builder. But don't panic -- you can download a Sandcastle package from CodePlex that includes a great "guided installation" wizard. The wizard will help ensure that you get everything you need: Sandcastle, the GUI, and the necessary Help compilers. Just make sure that you download from the CodePlex site -- a simple Google search can lead you to a Sandcastle site with outdated links.
Using Sandcastle with the GUI is easy: Select Sandcastle from the Windows Start menu, create a new project, and add to the Sandcastle project the assemblies you want to document (you can also add "reference" assemblies, which are not documented but which your documentation refers to). Once you've added all your assemblies, it's just a matter of clicking the Build button and waiting for your Help files to be generated. After the files are generated, you can view the resulting output from the GUI's view menu.
There are several plug-ins for Sandcastle. For instance, the Wildcard References plug-in allows you to add as references to your project whatever assemblies in a folder (and optionally, its subfolders) meet a filespec. Sandcastle also includes a tool for gathering up the XML comments from ASP.NET Web Applications and Websites (since ASP.NET projects may have multiple DLLs) so that they can be incorporated into your documentation.
Sandcastle doesn't integrate with Visual Studio 2010 or your project's file structure, though there's an alpha release of a package that has begun adding that feature. The package also has the odd limitation. For instance, you can't add a reference to a COM DLL through the GUI.
Does Sandcastle do everything Document! X does? No. Currently, Sandcastle lacks Document! X's integration with Visual Studio, doesn't support documenting databases or Ajax components, and lacks Document! X's source control features, among other options. However, if what you want to do is generate MSDN-style documentation for your assemblies, Sandcastle will do that -- and the price is right. It's entirely possible that Sandcastle will meet your current needs for documenting your applications and should you, eventually, need to do something that Sandcastle doesn't support, you can purchase a more comprehensive package.
Posted by Peter Vogel on 10/19/2011