Documentation Made of Sand

This is a follow up to my earlier post discussing the documentation options that are around for C# and VB.Net. Today I focus on getting custom themes etc on the output webpage.

How do you customize the output from Sandcastle and Sandcastle Help File Builder?

This is how we did it where I work. First I picked the settings (e.g. The presentation etc) that most closely matched the output style that we desired. Then I generated the HTML output and handed it all over to one of my trusty designer minions coworkers. Actually we didn't use HTML as the ASPX page gave much more options for customizations and everything else we do here is in ASPX anyway.

Once the designer wand had been waved over it I had lots of fun figuring out what I needed to change on the input side of things, that is which customizations I could achieve by changing SHFB settings and which ones I needed to delve deeper for.

The easiest spot to start with customization is within the Sandcastle/Presentation folder, once you have picked the "Presentation" that you like, simply duplicate it and make the changes in the duplicate (there is one tricky thing here though, SHFB needs to be able to link to the theme that you have copied and it does this by checking whether any of the default theme names are in the presentation folder so you'll need to rename the folder to something like _). For us however the only thing that we actually changed was some styles stuff in "Presentation.css" and modified a couple of the icons.

Unfortunately that's not enough customization for us, instead our final customization relied on modifying the main Index.aspx page substantially. The source of this is in the SHFB/Web folder and I discovered thankfully that as long as I didn't replace the single key insertion which was the @WebDefaultTopic section of the iframe link we could pretty much have at it. Thankfully SHFB automatically copies everything that is in the Web folder across to the website that it creates for the documentation so no further hacking was needed to ensure that the added images and htc files where copied to the output.

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.