Sandcastle, a documentation tool for the .Net 2.0 Framework
I promised to inform you about my experiences with Sandcastle, the new tool from Microsoft to help you generate documentation for .Net 2.0 components. In this post I would like to share some of my experiences with the first CTP of Sandcastle.
There will be more than one CTP before we reach Sandcastle 1.0 RTW. The next CTP, which according to the Sandcastle Team blog will be available somewhere in the next 2 weeks, will solve a number of issues that have been mentioned at the blog and at the Microsoft Developer Documentation and Help System forum.
At the end of this post, you will find a list of links to valuable information and downloads.
The test case
Before making a start with Sandcastle, I needed a good test case. Something for which I needed a help file and that would give me a good impression as to what the current Sandcastle CTP is capable of. For this purpuse, I used the set of class libraries I distribute amongst my colleagues at LogicaCMG, my current employer. For the .Net 1.* version of this library, I used NDOC which was a great tool. But NDoc never made it to a stable working version for .Net 2.0.
The full set of class libraries consists of 6 assemblies. The assemblies have references to .Net framework components. One assembly also contains references to a few Crystal Reports assemblies.
Installation experiences
Before you can install Sandcastle, you will have to make sure that the following has been installed on your machine:
- .Net Framework Version 2.0
- HTML Help Workshop
Once you have done that, it is time to run the setup for Sandcastle. The setup of Sandcastle is straight forward, as you would expect from a Microsoft product. I did not encounter any problems during the setup.
Sandcastle currently consists of a number of console applications, XSL transform files and data files. The following is a list of the Sandcastle applications:
- MRefBuilder: Reflects over managed assemblies to produce an XML-formatted reflection information file.
- BuildAssembler: Collates information from comment files and reflection information files into a set of HTML pages.
- XslTransform: Applies XSL transforms to XML files. This executable is used to generate and manipulate auxiliary data files.
Creating a help file for one assembly
At the Sandcastle Teamblog you can find a very comprehensive quickstart for creating a CHM using Sandcastle. Sandcastle relies on an XML configuration file which contains all the information required to build the help file. You also need to run the console applications in the correct order. It's obviously a lot easier to have a batchfile to do this, or possibly even an application.
If you only have references to .Net framework assemblies, then you do not really have a problem generating a CHM using the steps mentioned at the Sandcastle Teamblog. But when you have references to third party components, such as Crystal reports, then you can run into problems. As long as the components are installed somewhere in a folder on your system, then you can add the missing information in the MRefbuilder step by specifying the location of the components with a /Dep: flag. For example:
MRefbuilder
MyClassLib.dll
/dep:"C:\Projects\Output\DLL\ThirdParty.dll"
/out:reflection.org
Sandcastle at present does not support components that are installed in the GAC. It simply cannot find them. The 2nd CTP that will be released is going to address that problem. But until that CTP is released, you will need to place the GAC components somewhere on your system. I currently do this using the GetGACAssemblies application I blogged about.
A number of developers have created applications that automate the steps you need to take to create CHM file. Some examples:
At the moment, I use the GUI application created by Ashley van Gerven. It creates a batch file and a Sandcastle.config file. The batch file will to perform all the necessary steps to create a CHM file. It also supports creating a help file for multiple assemblies. Having a batch file is actually really good, because it allows you to solve problems with third-party dependencies quite easily.
I haven't had the time to see what the VS add-in by Frank Kroondijk can do, but that will happen soon. Other developers have built similar tools but for the moment I'll stick to these two. Especially since a GUI and VS Add-in have already been announced by the Sandcastle team, so I'm assuming that I will not need these tools for very long.
Creating the help file for all assemblies
When you need to document more than one assembly, you need to get deeper into the Sandcastle configuration file. This is an XML file that contains the steps needed by the Buildassembler application to build the topics for your help file. More details can be found here.
Fortunately, the GUI application created by Ashley van Gerven already takes care of this. Once the batch file and Sandcastle.config file was created by that GUI application, my help file was generated in a matter of seconds. As there is not that much documentation yet on Sandcastle, I really recommend looking at the various tools created by others on the internet when you want to start using Sandcastle.
The image below shows a screen shot of the help file for the CommandBuilder component I blogged about recently. The CHM file for the CommandBuilder component, wich I created using Sandcastle, can be downloaded here.
Flexibility
The look-and-feel of the generated help files are almost identical to the MSDN help files we all know. This is accomplished by a CSS stylesheet, a number of XSL files and some javascript. The way this is all setup allows you to influence the way your help files look. You can change the CSS to change the way the pages look. The XML files used for generating the HTML files that eventually get compiled into the CHM are modified using the XSL files. By changing these, or adding new files, you get even more control over the way information is presented.
What's still to come?
At the moment, the Sandcastle team is busy addressing issues mentioned by people who've used the first CTP. The next CTP, which is already announced, will solve a number of these issues. Somethings that are stll being developed before Before Sandcastle reaches version 1.0 RTM, according to information on the blog and forums:
- A GUI application to make creating help files easier.
- Improved HXS support to help integrate your help files in Visual Studio.
- Support for MSBuild.
- A Visual Studio Add-In
- Additional XSL and styles.
Conclusion
For what it's worth, Sandcastle has managed to make a good impression on me. I can create help files for my library again and the look-and-feel of the help file is that of the MSDN library. This obviously looks very familiar to everyone, so I'm quite happy with that. It's not that easy to work with at this moment, but I'm confident this will be solved once Sandcastle reaches 1.0 RTM. The features that are still to come, and the dedication of Microsoft to this project, I'm sure this will all work out.
Sandcastle resources
There is already lot's of information on Sandcastle available on the internet. Below is a list of resources that I found to be useful when you want to do something with Sandcastle: