Geeks With Blogs

News INETA Community Speakers Program
GeeksWithBlogs.net: WTFNext's hosting!

View Stacy Vicknair's profile on LinkedIn


WTF Next? Dev ramblings from a master of nothing.

If you, like me, have ever looked over the MSDN documentation and though how nice it would be to have that type of documentation for your codebase, SandCastle is the tool you’ve been looking for. SandCastle is a Codeplex project initiated by Microsoft in order to provide MSDN-esque documentation for .NET projects or asssemblies. The documentation can come in several formats such as CHM files or a website.

 

GhostDoc and SandCastle Help File Builder

To get started with SandCastle for documentation, I recommend a few additional tools: GhostDoc and SandCastle Help File Builder.

GhostDoc is a Visual Studio extension that allows quick XML documentation to be generated based on naming convention for methods, properties and parameters. XML documentation is the heart of how SandCastle generates documentation, so being able to quickly generate simple comments is a great benefit. The Pro version of GhostDoc also allows for customizations based on T4 templating.

SandCastle Help File Builder is a second Codeplex project that adds a GUI and additional support for SandCastle to make the overall experience of its use even better.

 

Installation

For a comprehensive installation guide, check out the SandCastle Help File Builder Installation Instructions. Their guided installer is easy to use and will verify that everything you need is in the right place. It will also let you know if you are lacking any dependencies you might need for generating specific help file types.

 

Usage

Once you have SHFB installed, open the SandCastle Help File Builder GUI and select File > New Project… then choose a location and name for your project. I follow the conventions for project naming that we use for any other project type and add the project to a subdirectory of the code solution.

image

SHFB saves projects as shfbproj types. These types can be built using MSBuild and incorporated into your current build processes. Do note that the time to generate documentation has a fair amount of overhead to reflect through your generated code.

After you have saved your project you can proceed to customize the sources to document by right clicking Documentation Sources then browsing to either the solution, project, or dll file you would like to include.

SS-2011-10-25_19.58.35

If you are looking to generate an HTML site specifically, this can be set on the HelpFileFormat under the Build section of the project properties.

SS-2011-10-25_20.04.16

Afterwards, just select Documentation > Build Project to create your very own MSDN-esque documentation!

SS-2011-10-25_20.09.45

 

Links

http://sandcastle.codeplex.com
http://shfb.codeplex.com/
http://submain.com/products/ghostdoc.aspx
http://www.ewoodruff.us/shfbdocs/Index.aspx?topic=html/8c0c97d0-c968-4c15-9fe9-e8f3a443c50a.htm
http://broadcast.oreilly.com/2010/09/build-html-documentation-for-y.html

Posted on Tuesday, October 25, 2011 1:15 PM How-To | Back to top


Comments on this post: Code Documentation Generation with SandCastle

No comments posted yet.
Your comment:
 (will show your gravatar)


Copyright © Stacy Vicknair | Powered by: GeeksWithBlogs.net