Sandcastle Help

Introduction

This document provides important information and links to various online resources for learning about Microsoft Sandcastle.

Key Points

Here are some key points that you should know about Sandcastle before you get started:

General Information

Usage

Output

Common Issues

When just starting out it's likely that you'll run into a few common issues when using Sandcastle:

Internet Access
Sandcastle resolves links to online MSDN topics using a web service, which requires Internet access. This feature can be disabled in the sandcsatle.config file at the cost of hyperlinks to MSDN content in your documentation. For more information, see this blog post.

Proxy Server
If a proxy server is being used for Internet access then Sandcastle must be configured appropriately. For more information, see Sandcastle and Proxy Servers.

Missing Code Comments in Documentation
By default, all of a project's XML documentation is expected to be in a single file named, comments.xml. If you have multiple XML documentation files then place them in a new folder named, Comments and adjust sandcastle.config to use a wild card instead, as in the following example.

<!-- Copy in comments -->
<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
           assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
  <index name="comments" value="/doc/members/member"
         key="@name" cache="100">
    <data base="%SystemRoot%\Microsoft.NET\Framework\v2.0.50727"
          recurse="false" files="*.xml" />

    <data files="Comments\*.xml" />  <!-- This line was modified -->

  </index>
  <copy name="comments" source="*" target="/document/comments" />
<components>

For more information, see this blog post.

Visual Studio 2005 and 2008 SDKs install a DXROOT environment variable for an older CTP
The SDKs install an older version of Sandcastle on your system and then create a DXROOT user environment variable pointing to the installation folder. This environment variable is vital for Sandcastle to work. However, newer versions of Sandcastle create it as a system environment variable. Since the user variable has precedence, the older CTP version of Sandcastle will be used when building on the command-line and when using automation tools.

This causes several related issues that sometimes aren't so obvious. It is highly recommended when installing an SDK that you take action before using Sandcastle. To fix this problem, delete the DXROOT user environment variable that was created by the SDK installer. Also, ensure that the DXROOT system environment variable was created by Sandcastle's installer and that it points to the Sandcastle installation folder; commonly, C:\Program Files\Sandcastle\.

Build Scripts

Microsoft has not provided formal documentation yet, however the installation comes with a few scripts that you can use to learn about Sandcastle's build process and tools and to get started building documentation right away:

Community Projects

Several products have been developed by the user community to improve Sandcastle's usability and to enhance its feature set.

Open Source GUIs for Sandcastle

The following open source projects provide GUIs for automating Sandcastle. They allow you to easily configure settings and build documentation with various output types:

Supplementary Community Projects

A few projects provide additional features for Sandcastle. They work with or without the automation tools listed above.

Related Downloads

There are a number of complimentary projects that are recommended to be used along with Sandcastle:
HTML Help Workshop
Provides Microsoft's Help 1.x compiler and GUI. Install this product if you want to build a distributable help package (.chm file) from the HTML topics generated by Sandcastle. Help 1.x files can be opened on any Windows system, stand-alone or included as part of the documented application.

Help 1.x enables context-sensitive help scenarios in managed applications and works with the .NET Framework's Help and HelpProvider classes.

Additional information about Help 1.x can be found on the Microsoft Help MVP Website - Help 1.x.
Visual Studio SDKs (2005, 2008)
Provides Microsoft's Help 2.x compiler and COM services. Install an SDK if you want to build a help collection (.HxS file) from the HTML topics generated by Sandcastle.

Help 2.x is useful for add-in, control and package developers that integrate their products into Visual Studio. An .HxS file can be merged with Visual Studio's help collections so that its documentation can be viewed in the Document Explorer, which is the external program that opens when you press F1 in Visual Studio.

Additional information about Help 2.x can be found on the Microsoft Help MVP Website - Help 2.x and in MSDN's Visual Studio SDK topics: Help Integration and Command-Line Programs.
AjaxDoc
Generates documentation for Atlas client script libraries. The XML documentation and reflection files that are produced can be used as input to Sandcastle and it will generate HTML topics that look like documentation for managed APIs.

XML Documentation

XML documentation can be generated automatically by managed compilers such as csc.exe (C#; use the /doc switch) and vbc.exe (VB.NET; use the /doc switch) from triple-slash /// comments in C# and triple-apostrophe ''' comments in VB.NET, respectively. Visual Studio can also be used to enable XML documentation output for your managed projects. For more information, see How to: Generate XML Documentation for a Project.

The compilers use a well-known schema to generate XML documentation files, which means that third-party tools and authors can write XML documentation as well. These files can then be passed to Sandcastle as input and it will include the data in the HTML topics that it generates.

Recommended Tags for Documentation Comments (C# Programming Guide)
http://msdn2.microsoft.com/en-us/library/5ast78ax.aspx

Recommended XML Tags for Documentation Comments (Visual Basic)
http://msdn2.microsoft.com/en-us/library/ms172653.aspx

Dynicity LLC's XML Documentation Comments Guide
http://www.dynicity.com/Products/XMLDocComments.aspx

Conceptual Documentation Using Microsoft Assistance Markup Language (MAML)

Sandcastle can produce conceptual documentation from MAML, which is a set of XML schemas that define structured authoring elements for creating help topics. This allows an author to focus on the content instead of the formatting, which is applied later by a Sandcastle presentation style.

Sandcastle comes with a set of MAML schema files (.xsd), which can help you to author documentation using IntelliSense in Visual Studio's XML editor.

Conceptual output can be combined with auto-generated reference documentation to produce mixed user and reference documentation for compiled help or the web.

MAML References
There is no formal documentation for MAML available yet, however there are some articles on the web that provide an overview:

Sandcastle MAML Guide
http://www.codeplex.com/SandcastleStyles

Sandcastle Conceptual Help: Quick Start
http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

MAML Migration: The Next Step in the Evolution of Help Authoring
http://davesexton.com/blog/blogs/blog/archive/2008/05/24/maml-migration-the-next-step-in-the-evolution-of-help-authoring.aspx

Microsoft Assistance Markup Language. In Wikipedia, The Free Encyclopedia. [Background]
http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language

MAML - Microsoft Assistance Markup Language [Schema reference]
http://www.help-info.de/en/Help_Info_AP_Help/longhorn_maml_example.htm

Online Resources

Some useful online resources for Sandcastle include:

David Wright and Anand Raman on Sandcastle (dnrTV interview/training video)
http://www.dnrtv.com/default.aspx?showNum=84

Sandcastle Blog
http://blogs.msdn.com/Sandcastle

MSDN Forum: Developer Documentation and Help System
http://forums.msdn.microsoft.com/en-US/devdocs/threads/

Sandcastle Wiki (Note: This may eventually become obsolete in favor of the dedicated MSDN page below)
http://www.sandcastledocs.com

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

Developer Documentation and Help System Forum
http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

Creating Custom Build Components for Sandcastle, by Eric Woodruff
http://www.codeproject.com/csharp/SandcastleComponents.asp