Building Sandcastles

It's a depressing feeling. You are full of hope as you configure the XML Documentation setting in the project properties (oh yes, this is VS2005).

You were confident about your diligence at filling out the XML Documentation comments, it seemed like everywhere....

Then the horror. Trigger the build, and 582 XML Documentation warnings. Wtf!!!?!

Ok, so 582 edits later, then what?

Oh yes, download the latest CTP of Sandcastle, and start generating documentation. It even makes it look like VS-style yumminess.

Mmmmm.... Forbidden donut....

Yes, but still a few issues to note:

• The DXROOT environment variable has a path-separator appended to it, which is not usually the custom. The "examples" script assumes there's no path-separator, and as a result, it generates double-path-separator in there.
• The assembly scanner (which generates the topic list by reflection) wants all dependent assemblies not in the GAC available in the current folder. The build_sandcastle.bat doesn't display this; I only figured it out running it from the command line.
• There is msbuild support also; I didn't try it. I am leaning toward making a NAnt version, to increase understanding.

Once that all got sorted, I was generating nice CHM files of my hard-typed-in XML Documentation!!