Using Sandcastle to build code contracts documentation

In my last posting about code contracts I showed how code contracts are documented in XML-documents. In this posting I will show you how to get code contracts documented with Sandcastle and Sandcastle Help File Builder.

Before we start, let’s download Sandcastle tools we need:

Install Sandcastle first and then Sandcastle Help File Builder. Because we are generating only HTML based documentation we upload to server we don’t need any other tools. Of course, we need Cassini or IIS, but I expect it to be already there in your machine.

Open your project and turn on XML-documentation for project and contracts.

Now let’s run Sandcastle Help File Builder. We have to create new project and add our Visual Studio solution to this project. Now set the HelpFileFormat parameter value to be Website and let builder build the help.

Sandcastle Help File Builder

You have to wait about two or three minutes until help is ready. Take a look at your documentation that Sandcastle generated – you see not much information there about code contracts and their rules.

Enabling code contracts documentation

Now let’s include code contracts to documentation. Follow these steps:

  1. Open Sandcastle folder and make copy of vs2005 folder.
  2. Open CodeContracts folder (c:\program files\microsoft\contracts\) and unzip the archive from sandcastle folder.
  3. Copy all unzipped files to Sandcastle folder.
  4. Create (yes, create new) and build your Sandcastle Help File Builder documentation project again.
  5. Open help.

In my case I see something like this now.

Sandcastle documentation with contracts

As you can see then contracts are documented pretty well. We can easily turn on code contracts XML-documentation generation and all our contracts are documented automatically. To get documentation work we had to use Sandcastle help file fixes that are installed with code contracts and if we had previously Sandcastle Help File Builder project we had to create it from start to get new rules accepted. Once the documentation support for contracts works we have to do nothing more to get contracts documented.

Gunnar Peipman

Gunnar Peipman is ASP.NET, Azure and SharePoint fan, Estonian Microsoft user group leader, blogger, conference speaker, teacher, and tech maniac. Since 2008 he is Microsoft MVP specialized on ASP.NET.

    2 thoughts on “Using Sandcastle to build code contracts documentation

    • August 5, 2010 at 10:42 am
      Permalink

      Hello,

      I was wondering which version of Sandcastle & Sandcastle Help File Builder you used for the demostration.

      I can not get it to work! Sandcastle comes complaining about something he can not find during transformation.

      I’m using Sandcastle-June 2010 Release (Version 2.6.1062.1) & SHFB 1.9.1.0.

      Thanks in advance.

      Best regards,

      Alexander

    • August 10, 2010 at 9:39 pm
      Permalink

      I was using earlier release and everything worked fine. You have to copy some files from code contracts folder to sandcastle folder to make sandcastle able to extract contracts information.

    Leave a Reply

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