Tuesday, August 26, 2008

What is SandCastle?

What is SandCastle?

The brief description of the product on the download page describes it as: Documentation compilers for managed class libraries Enabling managed class library developers throughout the world to easily create accurate, informative documentation with a common look and feel.

This is great description, so what is it?

Sandcastle a command line application designed to generate "MDSN style" documentation from .NET assemblies by using XML Documentation Comments. The product works with or without XML Comments in your code.

You can produce three types of documentation with the product:
HTML files
CHM (Help 1.0) Format
HxS (Help 2.0) Format

The product can produce the documentation using three different types of "themes"
Hana
Prototype
VS2005 - VS2005 documentation

Running your first Sandcastle example
1. Open a command prompt (as an administrator on Vista)
2. Navigate to your Sandcastle example directory (C:\Program Files\Sandcastle\Examples by default)
3. Run the setPath batch file (sets path for the command window)
4. Open the Sandcastle sub folder
5. build_sandcastle vs2005 test.dll
6. Review the result in the sub folder "Output"

The product currently only supports the 2.0 framework, and .NET versions that compile on it.

Interested? Download it here: Sandcastle - Version 2.4.10520

4 comments:

John said...

Are there any extensions that let it work on v3.5 of the framework?

Also, what do I inspect in the output file? Which files do I load and how do I look at them?

John said...

Also, I see that there is a SandCastleGUI. Is that something that would be helpful?

I would like to use this, but it's not totally clear on how I would use it. We already have the documentation in the source, so I would think that will work.

But, I can't seem to get much useful out of the even the test that comes with Sandcastle.

Christopher Hardwick said...

John,

Thanks for taking the time to read the blog.

SandCastle will work with the 3.5 framework, in the post I should have clarified that the product runs on the 2.0 Framework CLR, which is shared by 3.0 and 3.5

You can find more about the topic here on Scott Hanselman's blog

This article confirms the use of the product on 3.5 stating: "Supports Generics and .NET Framework 1.1, 2.0, 3.0, 3.5 and other released versions of Framework"

If you have any further questions, please do not hesitate to ask.

Christopher Hardwick said...

John,

Thanks for the inqury. I have not tried DocProject and SandcastleGUI for a user interface.

This is the link to DocProject if you want to try it out:
http://www.codeplex.com/DocProject

When I have some additional time, I will try to give them both a try and post about it.