Friday, February 27, 2009

From nDoc to Sandcastle

Summary: A new old way to generate documentation (help) files for .NET 2.0+ applications.

I owe Kevin Downs, the author of nDoc, a long delayed apology (nDoc is a popular open-source help file generator designed for .NET 1.x apps). Although I used nDoc extensively (in fact, it was one of my favorite development tools), I did not contribute to the project. The nDoc project died in mid-2006 and it was partially my fault. I'm sorry Kevin. Shame on me: I should've started celebrating Freeware Appreciation Day earlier.

[Not to shift the blame, but the role of Microsoft in the nDoc demise was hardly praise-worthy. I never understood Microsoft's approach to successful applications complementing -- notice, not competing with -- Microsoft technologies and tools: announce an alternative solution, overpromise, and underdeliver. Why wouldn't Microsoft cooperate with the authors of these applications in some way. I totally agree with Scott Hanselman's point:
"It's a shame that Microsoft can't put together an organization like INETA (who already gives small stipends to folks to speak at User Groups) and gave away grants/stipends to the 20 or so .NET Open Source Projects that TRULY make a difference in measurable ways. The whole thing could be managed out of the existing INETA organization and wouldn't cost more than a few hundred grand - the price of maybe 3-4 Microsoft Engineers."
Microsoft should've known better.]
Well, life went on and I needed an nDoc replacement, which would work with .NET 2.0+ apps. So I tried Sandcastle, the Microsoft-sponsored open-source alternative to nDoc, and to my surprise, it worked reasonably well. There was a couple of problems, though.

Problem #1: Sandcastle failed to convert a working nDoc project with error:
"Unable to convert project. Reason: Error CVT0005: Error reading project from 'C:\[...]\[...].ndoc' (last property = DocumentInheritedMembers): String was not recognized as a valid Boolean."
I posted this problem at the CodePlex Issue Tracker not expecting it to be noticed, but received a response on the same day. Since it was easy enough for me to create a new project, I did not use the suggestion, but if you encounter a similar issue, check out the replies to the Error CVT0005 converting nDoc project post.

Problem #2: My first attempt to compile the project failed with error:
"The imported project "C:\SandcastleHelpFileBuilder.targets" was not found."
After some poking around, I figured out that the environment variable SHFBROOT used by the help compiler did not take effect after installation. To fix it, I had to log off and log on to Windows.

After that everything worked well. You can see an example of the Sandcastle project and the generated help file in the Windows service demo project.

If you want to generate documentation from the XML comments in your Visual Studio 2005 (and later) projects, you need to do the following:
  1. Make sure that HTML Help Workshop is installed.
  2. Install the main Sandcastle app.
  3. Install Sandcastle Help File Builder (SHFB) (a GUI app used for building help files).
  4. Create a new project and add your Visual Studio 2005 (or later) project, solution, or output (DLL or EXE) file to the SHFB's documentation sources.
  5. Define other project properties and build the project.
I specified the HTML Help Workshop location in the Sandacastle settings, but this may not have been necessary. I also used Sandcastle to build HTML Help 1.x (.CHM) files, so I'm not sure how it works for HTML Help 2.x (.HxS) files.

If you are not sure about particular settings, check the provided help file or Sandcastle Help File Builder Overview. You can find a number of related projects -- such as DocProject for Sandcastle, Sandcastle Extensions, and others -- at CodePlex, but I haven't tried them. For the latest news, check the Sandcastle blog.

See also:
NDoc to Sandcastle - Generate MSDN Style Documentation and Help Files Based on XML Comments in your .NET Code by David Hayden
Microsoft's Sandcastle emerges as NDoc's creator calls it quits by Brian Eastwood
A Coder’s Guide to Writing API Documentation by Peter Gruenbaum
Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code by Michael Sorens

No comments: