S h o r t S t o r i e s

// Tales from software development

Wrestling with SandCastle

leave a comment »

SandCastle

I’ve spent the past week putting together a general purpose build for .NET 2.0 and 3.5 projects. Because the NDoc project appears to have ground to a halt I decided to use Microsoft’s SandCastle instead to generate documentation in the build.

SandCastle is used internally at Microsoft and was used to generate the .NET Framework 3.5 documentation. So, I was expecting a mature and robust tool. After struggling with it and making very little progress other than to find one bug after another I conceded defeat. There had to be an easier way…

I searched the SandCastle related forums and blogs and quickly found myself agreeing with the guy who posted the comment “…this is insanely complicated…” on the CodePlex site. However, the fact that there are several tools available that act as a front end to SandCastle gave me hope. To paraphrase another poster’s comments, SandCastle is better thought of as being the infrastructure for generating documention and an NDoc-type tool is still needed to use it.

First I tried using some of the batch file and build script tools that claim to make using SandCastle easy. I found that most were out of date as they are based on early CTP versions of SandCastle and no longer work with the latest (May 2008) release. The ones that did appear to have been updated to work with the current release usually failed when they encountered the same bugs that I’d already encountered when using SandCastle directly.

SandCastle Help File Builder

Finally, I decided to try Eric Woodruff’s SandCastle Help File Builder tool. Thank goodness there’s someone who fully understands SandCastle because Eric clearly does and he’s produced a tool that exposes all of the power and functionality of SandCastle through an easy to use UI. He’s also understood the need to incorporate this functionality into build scripts and has included a command line utility to build SandCastle Help File Builder projects.

Eric has also found ways of working around the known bugs in the current SandCastle release and the issues that I found when using SandCastle directly have simply disappeared.

MTPS Content Service

One of the irritations mentioned by SandCastle users is the fact that SandCastle attempts to access a Microsoft web service and fails if it cannot. A little bit of investigation shows that this is because, by default, SandCastle uses the MTPS Content Service. This service exposes navigation links for MSDN content. Presumably, this feature is on by default because SandCastle was developed at Microsoft to generate MSDN documentation.

Thankfully, not only can this behaviour be changed but SandCastle Help File Builder makes it easy to do this. Under the Help File section of the Project Properties window there are two properties that control how content links are generated: SdkLinkTarget and SdkLinkType

The SdkLinkTarget property specifies how the linked content is displayed in the same way as the target attribute of an HTML anchor.

The SdkLinkType property defines the type of link to be used. The default value, Msdn, causes SandCastle to access the MTPS web service to get the navigation link for an MSDN topic. Changing the value to Index or None stops this.

Documenting Namespaces

One other issue to note is that SandCastle can generate NameSpace comments but there is no support for this in Visual Studio’s  XML Comments system and so NameSpace comments must be supplied to SandCastle. Again, SandCastle Help Builder has this covered.

At the top right of the UI you’ll see a group of buttons. The Prj Summary and Namespaces buttons allow you to provide comments for the project and the namespaces.

Resources

SandCastle 2.4.10520 (Microsoft Download Center)

SandCastle (CodePlex)

SandCastle Help File Builder (CodePlex)

 

Advertisements

Written by Sea Monkey

December 16, 2008 at 9:00 pm

Posted in Development

Tagged with

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: