Using Sandcastle

You Mean I Actually Have to Use Sandcastle? Yes, with the death of NDoc, if you want to generate a chm based on triple-slash comments then you will probably need the help of Sandcastle.

It was nice of MS to release this thing - really. It would have been nicer if they would have sent a team to help NDoc, but let's not dwell on what could have been.

Using the August CTP I quickly found myself in hell. It was one thing to follow the directions for the sample. It was a whole other thing to actually build docs for my own projects. I created a bit of the hell for myself by trying to build docs in the directory structure of the project for which the docs are meant to be a part. I am sure I am not alone in this desire - it makes source control and packaging so much simpler.

I'll skip to the end and let you know that the results are quite nice - I am glad to have the docs. Everyone acknowledges the problems, and in fact there are some great helper articles referenced in the comments - mostly here. Heck, one guy even created a nice batch file and configuration doc builder. Unfortunately, it doesn't actually create usable batch file - at least not for me. It was faster to fix the batch I was working on than to debug his tool. That tool would be a great thing to spend some free cycles on and fix - but then look what happened to NDoc, so we can be sure that will never happen.

Another guy created a serious batch file here - again I couldn't make it work for me.

There are a few morals to this story:

1. 1) Batch files and esoteric config files without good docs are always hell to work with. Be prepared to dig in.
2. 2) Just hard code all the folder/file references in the sandcastle.config to full paths. You can try to be all fancy, but this is just a CTP and there are more robust versions to come. Besides, it's just install locations and that isn't too bad (in fact, the config doc creator tool mentioned above actually does a nice job on this).
3. 3) Create all the content folders (html,scripts,art,styles) directly below the batch so BuildAssembler doesn't get confused
4. 4) A much discussed batch line from the examples where the results of one transform are piped into another XslTransform statement is total BS - it never worked until I split the line into another statement with results from the first. Not sure why someone felt they needed the pipe to begin with.
5. 5) Don't try to name any help doc transform results to anything other than test.[hhc,hhp,hhk]. I don't know anything about the hhc API, but it sure doesn't like to work with anything other than test. Just rename the output, test.chm, to something else at the end of your batch file.