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.