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

  • Sandcastle is currently released on CodePlex (http://www.codeplex.com/Sandcastle).
  • Sandcastle is also bundled as an older community technology preview (CTP) with the Visual Studio 2005 and 2008 SDKs.
  • Sandcastle is based on Microsoft's internal tools that are used to build documentation for Visual Studio and the Microsoft .NET Framework.
  • In the past, a new CTP version of Sandcastle was released approximately every 1 to 3 months. This pattern is expected to continue.

Usage

  • Sandcastle is not a single executable program but is actually a set of programs and XSL transformations that must be used together.
  • Sandcastle is extremely flexible and offers many configurable features.
  • Sandcastle's build process can change depending upon the desired output, format and presentation style, so there isn't one universal process that can meet everyone's needs.
  • Sandcastle can be used in various scripts such as batch files, MSBuild and PowerShell. (See Build Scripts below for more information.)
  • Sandcastle provides an example graphical user interface (GUI) that automates an MSBuild script, but it does not provide Visual Studio integration and many of the desirable features that users have come to expect from help authoring tools (HATs); although, the open-source community does. (See Open Source GUIs for Sandcastle below for more information).

Output

  • Sandcastle supports different presentation styles, including one that looks like the documentation for Visual Studio and the Microsoft .NET Framework.
  • Sandcastle produces XML-based HTML topic files using two different processes, which can be combined together to produce mixed documentation:
    • Conceptual documentation (e.g., custom topics, walk-throughs, how tos, troubleshooting) is built from Microsoft Assistance Markup Language (MAML). (See Conceptual Documentation Using MAML below for more information.)
    • Auto-generated reference documentation is built for managed and unmanaged application programming interfaces (APIs).
      • Reflection information for managed assemblies can be generated automatically by Sandcastle's MRefBuilder.exe program.
      • Reflection information for unmanaged libraries must be generated by a third-party tool. (AjaxDoc is one example.)
      • Sandcastle can optionally integrate XML documentation from code comments or external tools into auto-generated topics. (See Xml Documentation below for more information.)
      • Sandcastle will pass through many common HTML tags in XML documentation (code comments), such as <p>, <img>, <strong>, etc.
  • Sandcastle itself does not build compiled help (e.g., HTML Help 1.x, 2.x) but the installed build scripts enable this scenario out-of-the-box with some additional software. (See Related Downloads below for more information and links to downloads.)

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:
  • Graphical User Interface (GUI): Examples\generic\SandcastleGui.exe
  • MSBuild project: Examples\sandcastle\build.proj
  • Command-line batch script: Examples\sandcastle\build_Sandcastle.bat
  • Windows PowerShell script: ProductionTools\scbuild.ps1

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:
  • DocProject: Visual Studio 2005/2008 integration using MSBuild project templates, an Add-In and GUIs.
  • Sandcastle Help File Builder: A popular NDoc-style GUI and console-mode application with custom build components.
  • Sandcastle GUI: Another popular GUI for Sandcastle.

Supplementary Community Projects

A few projects provide additional features for Sandcastle. They work with or without the automation tools listed above.
  • Sandcastle Styles: Provides a rolled-up solution to various presentation style issues as well as additional resources that are useful to Sandcastle users.
  • Sandcastle Extensions: Provides a few Sandcastle build components and SHFB plug-ins that, for example, add the ability to add Help 2.x meta attributes and to have collection-level Help 2.x files generated automatically.
  • Drawbridge: Sandcastle build component that transforms Visual Studio class diagrams into images when it finds references in XML documentation, at build-time.

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

Last edited Jul 2, 2008 at 7:43 PM by davedev, version 25

Comments

No comments yet.