SandCastle and DocProject

Creator of DocProject, Dave Sexton, made some interesting comments about his software on my previous posts about Sandcastle and Creating Sandcastle websites which made me want to look at his software again. DocProject is quite different to the other UI’s for Sandcastle as it actually integrates into Visual Studio and MSBuild so very easy to integrate into new and existing solutions, Dave has also put good How To’s on the site for getting started with the project. For this post, I am using version 1.6.2 RC and June CTP Refresh of Sandcastle.

I plan to have DocProject generate both compiled help in CHM and HxS format and also output a website for an online version of the help files for an existing solution, SandcastleDocumentationTest. Following Dave’s advice, I ran Visual Studio as Administrator on Vista, if you don’t you will run into problems and load my solution like normal. I then add a new project, and under the Visual C# tab select DocProject and the Project Documentation item. It then gives you a simple wizard, where you can select the output type, assemblies to output, and template is a very simple and straight forward way. After it has done that, in the solution there will be a project for your documentation.

The first thing I did was do a build, as it uses MsBuild this was done right within Visual Studio which was nice. It would have been cool if the Sandcastle output was also being displayed as part of the build, within the build windows as Sandcastle tasks a while and knowing what is happening would be nice. (Turns out, after the Addin is loaded, it actually does this, makes for a much better experience – you even get a progress bar on the status.). Note, while this is building, you can’t rebuild your main solution so one of the recommendations is “Open the solution configuration manager and for each configuration (e.g., Debug and Release) uncheck the Build column for the DocProject so that it’s only built on-demand and not when the solution is built.” Once the build has finished, in the project directory you will find the complied help files, or select Show All Files in VS for the project and it will be listed within the solution. So its really simple to get going with this and to output your first project.

Now that we have a base project in place, we can look at extending it. DocProject integrates into Visual Studio’s Options menu (Tools > Options > DocProject) which lead onto my second sight problem, the Addin wasn’t being extended into the Options menu, after one or two quick emails to Dave it turns out the problem was with Visual studio and his software did the correct thing.

So, with the addin now loaded correctly, I can look at the software. With the Options menu, DocProject provides you with the core options for the current active project. The main options which I like are

Use friendly HTML file names

API Topic Management, where you can set summaries for the namespaces

API Topic Designer, for HTML header and footer for docs

The API Topic Management and Designer are also accessible via a toolbar which is installed.

So that’s how to configure the additional options, all the settings are saved into project.xml. Now we have our documentation being created in an offline format, lets have a look at how to create it in an online format.

The other project template which is provided is for DocSite. This option creates a ASP.net Ajax enabled website to display the created documentation online. It also outputs the CHM and HxS which are linked to the main site so the user can download them. This means that you could just have one build which outputs all the three formats for your help which is nice. The site itself looks really nice, uses ASP.net master pages so can be easily modified and is good enough to put on your site, in fact the Xml MVP’s have here. One problem is that the search doesn’t work with partial worlds, for example Hello doesn’t bring up HelloWorld which is a shame and the icons look very much like 98 style help – having simple +/- like MSDN could look better. But that’s one of the great things about DocProject, if you want a different icon then you just need to change the style sheet. But, its great that the site is provided to the standard out the box.

Finally, as I mentioned. Because this is just a MSBuild script, it can be easily executed as part of a build and the output included within your install/package.

Summary

So, I was wrong, DocProject is a very nice tool and really worth using, so is SHFB. My experience was tainted by the Addin problem wasn’t the project’s fault. After that was installed, it worked like a dream! The fact that the website it outputs looks amazing and is ready to go is a big plus, together with the fact that it is just a MSBuild script makes it so simple to integrate into an existing project or build script.