SandCastle – What you need to know

Recently, the SandCastle team released the June CTP of their software, so I decided to dig a little deeper and see what Sandcastle offers and how it works.  Note, the Sandcastle team released the June CTP on Friday 22nd, however released a Refresh a few days later renaming the template VSOrcas to Hana and making it look a lot cleaner.  If you was a little quick off the mark with your download, you will have to re-install the refresh.

Sandcastle is a command-line application which takes XMLDocs (/// comments at the top of classes and methods) from your .Net code and output them in a readable and distributable format.  Microsoft are using Sandcastle to produce both internal and external documentation on the .Net framework and seems to have a lively release schedule.

After installing the CTP, as there isn’t a GUI or any kind of integration, you are left to search for everything yourself.  Luckily, there are a range of GUI’s and help support available online which I will cover later.  For now, I’m just going to cover the core application.

Sandcastle can produce three types of help file format.

  • HTML files
  • CHM (Help 1.0) Format
  • HxS (Help 2.0) Format

These are styled based on predefined themes within the framework, these should fit most of your requirements and you can add your own however that’s beyond the scope of this post.  I think you create another folder similar to the ones in C:Program FilesSandcastlePresentation, however I’m not 100% sure on this.  The three styles included are:

  • Codename Hana. This is new within June CTP, this was called VSOrcas however due to VS no longer being called Orcas this had to change.  This will be the template for .Net 3.5 help I think.
  • Prototype.  Some ideas which have been now migrated to Hana
  • VS2005.  2005 style documentation.

This gives you enough flexibility to be able to produce helps files to meet your own needs with the look and feel you want.  Lets have a look at how to create the files.

Included within the install is an example folder which can be used to check everything is working, and for you to quickly see what the output of each template and XmlDoc tag looks like.  Within the directory C:Program FilesSandcastleExamplesSandcastle there is three files.

  1. build.proj – MsBuild script
  2. test.cs – Documented sample code which will be built.
  3. build_Sandcastle.bat – Batch file for creating the output.

The example is very simple to run, unless your running vista.  If your running vista, the build will try and save files into the Program Files directory, if your not running the command prompt with Administrator rights, its going to fail in a not very helpful way.  Either run the cmd with admin rights (right click > Run As Admin) or copy the examples to a directory you can write too.  I copied the Sandcastle examples directory to my own space to work with. Once you are in a position to run the build you will need to execute the batch file and pass in a parameter for which template you would like to use,  for example “build_Sandcastle.bat Hana” or “build_Sandcastle.bat vs2005”.  Creating the example takes a while, a minute on my laptop so if your machine is a little old then it could take longer – or my laptop is just slow. Once it has been done you will notice a lot of new files in the examples directory, but the most important file is in the new Output folder and is called test.chm.  This is the help file created from the XmlDocs using the standard Microsoft Compiled Help Format. 

Screenshot of Hana output
Screenshot of output using the Hana template.

If you want to have a closer look at the samples, you can download Hana here and vs2005 here.  So that’s what is created by default, lets have a little closer look at what is going on under the covers.

Within the batch file, there is a number of different commands it executes in order to process the creation of the help file.

  1. Set PATH variables.  When installing Sandcastle, it should create a Environment Variable called DXROOT which points to the install directory.  The script just makes sure all the Path variables are set for it to use the command names without having to type in the directory names.
  2. Create the output directory where all the useful files are to be placed.
  3. Compile the test.cs file.  Output all of the comments to a separate file called comments.xml.  There is an checkbox within VS2005 Build settings for a project to enable this compiler option.
  4. MRefBuilder is then called which reflects on managed assemblies to produce an XML-formatted reflection information file.  This XML file contains everything about the assembly, all the classes, methods, properties, type information etc. Everything you would expect to see via Reflection. Produces (reflection.org)
  5. The code then applies some XSLT to the output file from MRefBuilder to produce reflection.xml.  The transforms it applies depends on the parameter passed in. 
  6. It then calls more XSLT on the reflection.xml to produce manifest.xml.
  7. A batch file is called which copies all of the output from one template to the output folder for local use.
  8. BuildAssembler is called which combines the reflection information generated, together with the comments file to create a set of HTML files.
  9. More XSLT based on reflection.xml is called to create a hhp (HTML Help Workshop Project) file.
  10. The Table Of Contents is then created, again using XSLT and reflection.xml.
  11. Finally, the chm is created using a bit more XSLT and the hhc exe.  Creating the document is complex process, using lots of XSLT but thankfully
  12. There is one more step, Generation of a HxS file.  I will discuss the HxS below.

That’s how it creates the file, but now lets look a bit more closely at what is actually created.

CHM (Help 1.0) Format

CHM has been around since Windows 98 and is a way to distribute help files, with open source readers for other platforms.  The format is viewable windows without installing any additional readers, so makes it a perfect choice for targeting the most people with the new templates actually making the contents look acceptable. The format is a bit limiting, doesn’t really offer much but offline HTML.  Simple but effective.

HxS (Help 2.0) Format

HxS is a bit more interesting, but also comes with added complexity.  HxS was first released under the VSIP license with VS2003.  It has now been included within the Visual Studio 2005 SDK, which must be installed in order for Sandcastle to be able to create the HxS help files. 

So, why would you actually want to use it?  Well, the purpose of HxS is to integrate into the Visual Studio help system, so instead of having to load a separate file you can simple hit F1 within VS and go to the help section. However, it comes at a cost.

Firstly, you either need to use Visual Studio to view the help file, or a separate application, such as H2Viewer.

Secondly, you need to actually install the help file using a MSI. There is a walk through on MSDN and the process isn’t very complicated, however if your install script is not MSI, i’m not sure how easy it is to integrate which could cause some issues.  Also, not sure how to integrate it into an existing MSI however I think this is just because of my limited installer knowledge.

To get the batch script example to work, I had to add the directory of where hxcomp.exe is located to the PATH variable, which on my system was: 

C:Program FilesVisual Studio 2005 SDK2007.02VisualStudioIntegrationArchiveHelpIntegration

You can see the output here, but you will need something to view it.

Hopefully, that has given you an overview so the different sections but doesn’t really provide you with any information for your own project so let’s look at the GUI support and how to integrate Sandcastle into your build script, but also why you might not want to.

GUI Support

There is a range of GUIs for Sandcastle, each very different and tailor to your own requirements and needs.  There are two main projects on codeplex, one is DocProject which integrates into Visual Studio where you include the template within your solution and reference the assemblies you wish to document, it can then create the help files when the project is built.  It’s good as it integrates into Visual Studio, but I found it to be more difficult to configure and it doesn’t work well with Vista.  The other is Sandcastle Help File Builder, SHFB, also on codeplex.  I found this to be very easy and straight to the point. You reference an assembly and then set a series of properties for the help file like you would on a object in Visual Studio. It can output both CHM and HxS, but you can also include your own custom files which can then be included as additional ‘pages’ within the help file, this is good for getting start documents or licensing information – DocProject also allows for this.  You can then click build and have the help files created for you. The only requirements are that Sandcastle is installed, and the Visual Studio SDK if you want Help 2.0 content.  The great thing is, you can save all of the settings in an external file for use again.

Automating

There is two ways to integrate Sandcastle into your build process, one way is via MSBuild with complicated script commands, or if your using SHFB you simply have a command which executes the Console part of the application, passing in the shfb project file which can be saved via the GUI and it will create your help files with the latest source.


  
  

If your using DocProject, then you simply need to build the project and this will output the files.

However, you might not want it executing every time you build the system as it will definitely add a lot of time onto your build process.  Just something to take into consideration.

Summary

That is an overview of Sandcastle and what it can offer.  Sandcastle is really good and its improving all the time.  While there is no official GUI’s or integration yet, the existing projects available are up to the task in hand. I hope it has been of some use to you, if you have any questions then please let me know.

Links

Samples I created from Example: Hana Help 1.0 | VS2005 Help 1.0 | Hana Help 2.0

Download: http://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

Visual Studio SDK: http://msdn2.microsoft.com/en-us/vstudio/aa700819.aspx

Creating MSI for HxS: How to- Use the Help Integration Wizard to Add a Help Collection to Visual Studio

MSDN: http://msdn2.microsoft.com/en-us/vstudio/bb608422.aspx

Sandcastle projects on Codeplex: http://codeplex.com/tagging/tagdetail.aspx?tagname=sandcastle

Sandcastle Help File Builder

Technorati tags: ,

One thought on “SandCastle – What you need to know”

  1. Hey. I was searching the web to see what the blogging community was saying about DocProject and I discovered yours. Thanks for mentioning it 🙂

    I’d just like to clear up a few things:

    1. The last 4 or so versions of DocProject were built on my Vista box, so I’m curious to know what incompatibility with Vista you’ve noticed. I’m aware that the CAS requirements are high, but that’s unavoidable, so you should run VS as an Admin. Microsoft recommends to anyway.

    2. I actually tried to make configuration in DocProject extremely easy. I guess I failed? The wizard provides basic configuration, then the Tools > Options > DocProject pages provide further configuration, and last but not least, you’re not restricted to use GUIs to customize Sandcastle’s config and transforms. You can configure Sandcastle directly using Visual Studio’s XML editor.

    3. It’s actually very easy to use DocProjects and DocSites on the command-line without any further configuration to the project files. For example, just run:

    msbuild.exe c:your_docproj.csproj

    4. I agree with your point that you generally wouldn’t want DocProjects built with your solution, which is why I recommended in the wikis that you should exclude DocProjects from the solution’s build configuration.
    See the “Creating a DocProject or DocSite for a new solution” wiki.

    – Dave

Leave a Reply

Your email address will not be published. Required fields are marked *