Is there a good quick start guide for generating API docs with Sandcastle?

Question

Hi,

I'm going to be generating API docs using Sandcastle - I couldn't find any guides on how to do this on there website. Does anyone have any quickstart guides they would recommend?

Answer 1

I'd suggest using SHFB (if you can), as it makes it really easier. SHFB comes with documentation, but you will be able to use it's common features without any tutorial.

Answer 2

Maybe you could check the (codeplex) site of SandCastle. But my experience is that it is best just to play around with it. First thing you have to do is configure your application to generate your comments into an XML file (and using XML comments in your code). This is a setting in your project.

Next thing you can do is load your assembly with the associated XML into Sandcastle and play with the settings (in most cases the default settings are good enough). Most settings are self-documenting or are obvious by looking at the name.

Good luck playing with it!

Answer 3

I am also a strong support of SHFB, so much so that in September 2010 I wrote a sizable article on Sandcastle and SHFB entitled Taming Sandcastle: A .NET Programmer's Guide to Documenting Your Code wherein I describe usage tips and a lot of the potential pitfalls one is likely to encounter. In October 2010 I followed that up with a one-page wall chart that summarizes the XML documentation comment lexicon for SHFB.

From my research for the article, here is a complete list of other useful resources:

• Eric Woodruff’s Sandcastle Help File Builder Documentation (SHFB Creator)
• C# Programming Guide: Recommended Tags for Documentation Comments (MSDN)
• Wm. Eric Brunsen’s XML Documentation Comments Guide (Dynicity)
• Anson Horton’s XML Documentation in C# (Microsoft C# Compiler Program Manager)