C# Documentation Generation

Seriously I didn't think it would be that hard, all we needed was documentation on a couple of C# projects for an API that we where releasing unto the unsuspecting masses. Java has JavaDoc, C# has nothing, well basically nothing.

DoxyGen is a jack of all trades document generation tool, which does work with C# (and C++, C, Java, PHP, Fortran...) we tried this but for some reason it doesn't resonate with the developers that I work with and really when you think about it. Why doesn't Visual Studio (which we use for everything as we're a windows .Net development shop) have built in documentation tools?

C# is Microsoft's language and they added the ability to document your code with \\\ style comments. Unfortunately the ability to get comments out of the code into some form that is appropriate for documenting an API, has been ignored or rather, not yet standardized or implemented or whatever excuse MS wishes to use.

A bit of poking around reveals that MS has their own tool which they use to generate their MSDN API documentation, Sandcastle. Sandcastle is possibly the most poorly documented project in existence. (In fact I wondered if it was a deliberate attempt at irony but then just remembered how lazy developers are). Thankfully there are some other kind souls out there that have bludgeoned through figuring out how to use Sandcastle and they developed Sandcastle Help File Builder which is a GUI for running Sandcastle and also gives you the ability to generate .chm files if you so desire.

In my case we just want the HTML output as we're going to be hosting it on a webserver. Playing around a little but with SHFB (namely changing the HelpFileFormat) allows me to get output as a webpage instead of the default .chm output format. This is pretty good, but we needed to get it styled up so that it fitted in with the rest of our sites. No worries, I'll just read through the documentation on how to do it.

Creating New Presentation Styles

TODO - recommendations and examples on creating new presentation styles (generally inherit from an existing style)

Ahhhhh, hmmm, did I tell you how awesome the documentation for this is?
It turns out that the best way to change the design and style is to copy and existing style and modify it with the additional complication that SHFB requires that the new style contain the name of the style that you have copied (go figure that one out....).
So after figuring it all out I found this post which pretty much explains everything and could have saved me a little bit of time. Anyway, the basic steps are as follows

1. Install Sandcastle and SHFB and its prerequisites. 
2. Open up SHFB and start a new project. 
3. Select the sources you want to use by "Adding Documentation Sources" 
4. Tweak the settings as desired. 
5. Click build. 
6. The output will open in a new browser window. 

Thats the basic steps, next step is I have to figure out how to get rid of the web page errors, which are caused because of a reference to a link of type "ms-help" in the html files. These links are apparently needed for when the .chm files are being generated but all they seem to do in my case is cause errors. It turns out that each "Presentation" has a "Transforms" folder associated with it so by commenting out the offending ms-help insertions I can alleviate that problem.
Next step is to figure out how to customise the header fully, currently we seem to be only allowed to change the text and perhaps stick an image in using the Post-Transform Component perhaps that will be sufficient for us.