July 16, 2014

NuGet Package for Sandcastle

Did you ever want to build Visual Studio-quality reference documentation from your XML code comments by simply referencing a NuGet package?
Well now you can!

The latest release of White Tie includes full support for generating documentation using Sandcastle. No configuration necessary. (You must install Sandcastle yourself though - see the details below).

Add a reference to White Tie's NuGet Package and then simply build your project in Release mode to generate reference documentation.


If you haven't installed Sandcastle, then White Tie gracefully skips generating documentation. You must install Sandcastle yourself if you want White Tie to generate documentation for your project. Note that you may have to reboot your computer after installing Sandcastle for its changes to take effect. At the very least, you'll have to restart Visual Studio.

White Tie's only requirements are that you must install Microsoft's HTML Help v1 Compiler and Sandcastle's tools. The required steps are highlighted in the following image of the Sandcastle Guided Installer. The other options provided by the installer, such as SHFB Visual Studio Package, are not used by White Tie at all. Of course, you're free to install them anyway if you'd like.

White Tie's Required Sandcastle Installer Steps

After you've installed Sandcastle, documentation is generated automatically when you build your project in Release mode. This is configurable via MSBuild properties, as is almost everything in White Tie (see the following section for details). The result is a compiled help file (.chm) in your project's output folder (typically, bin\Release\). In addition, White Tie packs the compiled help file into the NuGet package that it generates for your project as well.

Documentation Configuration

The purpose of White Tie is to make packaging and deployment of OSS projects, or any other kind of project, really simple. White Tie uses sensible default configurations across all of its features. However, it's also highly configurable to allow for customizations.

White Tie offers many configuration options in the form of MSBuild properties and items that control if and how documentation is generated, a NuGet package is generated, static analysis is executed and output is copied to a local deployment directory.

The configuration options for generating documentation (as of White Tie v1.3.5) are as follows.
See the official documentation for details.

MSBuild Properties

  • $(BuildDocumentationEnabled)
  • $(DocumentationProjectName)
  • $(DocumentationProductName)
  • $(DocumentationCompanyName)
  • $(DocumentationCopyright)
  • $(DocumentationVersion)
  • $(DocumentationProjectSummary)
  • $(DocumentationRootTopicEnabled)
  • $(DocumentationRootTopicTitle)
  • $(DocumentationFeedbackEmail)
  • $(DocumentationFeedbackLinkText)
  • $(DocumentationHeader)
  • $(DocumentationFooter)
  • $(DocumentationStyle)
  • $(DocumentationLanguage)

MSBuild Items

  • @(DocumentationContent)
  • @(DocumentationImage)
  • @(DocumentationNamespace)
  • @(DocumentationSource)
  • @(DocumentationReference)
  • @(DocumentationFrameworkReference)

Undocumented Sandcastle Configuration Properties and Items

Advanced users of Sandcastle may be wondering how to configure Sandcastle's many other options that are missing from the list above.

Well, in addition to the properties and items listed above, White Tie supports several properties and items that are specific to Sandcastle; however, I've decided to separate these options from the primary group because they aren't general enough for White Tie. In the future, White Tie may support other documentation generators, and perhaps even replace its dependency on Sandcastle entirely. As a result, if you restrict your use to only those configuration options listed above, then in the future you shouldn't have to change anything in order to take advantage of whatever new ways White Tie generates documentation for your project. For example, I can imagine Microsoft offering a very fast and light-weight Roslyn documentation generator and in the future I'd like any project depending on White Tie to switch automatically, with little to no changes necessary, by simply upgrading to a newer version of White Tie.

If you really want to use Sandcastle-specific features anyway, then here they are:

  • $(_SandcastleCopyrightUrl)
  • $(_SandcastleVisibleItems) - Default value is "Attributes, ExplicitInterfaceImplementations, InheritedMembers, InheritedFrameworkMembers, Protected, ProtectedInternalAsProtected"
  • $(_SandcastleMissingTags) - Default value is "IncludeTargets"
  • $(_SandcastleIntelliSenseOutputEnabled) - Default value is "true"
  • $(_SandcastleCodeRemoveRegionMarkers) - Default value is "false"
  • $(_SandcastleHelpFileFormat) - Default value is "HtmlHelp1"
  • $(_SandcastleSdkLinkTarget) - Default value is "Blank"
  • $(_SandcastleSyntaxFilters) - Default value is "Standard"
  • $(_SandcastleHelp2SdkLinkType) - Default value is "Msdn"
  • $(_SandcastleContentPlacement) - Default value is "AboveNamespaces"
  • $(_SandcastleNamingMethod) - Default value is "Guid"
  • $(_SandcastlePreliminary) - Default value is "False"
  • $(_SandcastleBuildAssemblerVerbosity) - Default value is "OnlyWarningsAndErrors"
  • $(_SandcastleNamespaceGrouping) - Default value is "True"
  • $(_SandcastleMaximumGroupParts) - Default value is "2"
  • $(_SandcastleCatalogName) - Default value is "VisualStudio12"
  • $(_SHFBApiFilter) - Default value is "<ApiFilter />"
  • @(SandcastleColorizer) - Default list is "cs;vb"
  • @(SandcastleComponent) - Default list is empty; however, the Code Block Component, API Token Resolution and IntelliSense Component are included immediately before building, so you cannot remove them.
  • @(_SandcastleHelpAttribute) - Default list is "DocSet;DocSet;TargetOS". The Value metadata of these items are {@HtmlHelpName}, NetFramework and Windows, respectively.
  • @(_SHFBTransformArguments) - Default list is empty. You may include: logoFile, logoHeight, logoWidth, logoAltText, logoPlacement, logoAlignment, maxVersionParts and defaultLanguage. Set the Value metadata to the desired value for each item.
  • @(_SandcastleContentLayoutFile) - Default list is empty.
  • @(_SandcastleCodeSnippet) - Default list is empty.
  • @(_SandcastleTokensFile) - Default list is empty.
  • @(_SandcastleResourceItems) - Default list is empty.
September 13, 2009

Sandcastle with Code Contracts

Microsoft Dev Labs has released a new version of Code Contracts.  (For more information about Code Contracts in the .NET Framework 4.0, see System.Diagnostics.Contracts and this article).  If you haven't yet, I highly recommend installing the latest Code Contracts release.  If you're using Visual Studio 2008 then you'll also get a shiny new tab in your project's Properties window.

Shiny New Properties Tab

Figure 1: Code Contracts tab in Visual Studio 2008 project Properties window

Along with the latest features is a new tool that adds documentation for Code Contracts to an assembly's XML documentation file.  The latest release also includes a Sandcastle patch that allows the vs2005 style to include the code contract documentation within an expandable Contracts section, as shown in the following screenshot.


Figure 2: Example Sandcastle output with Contracts section

The following blog post describes how you can patch Sandcastle so that it uses Code Contracts in XML documentation files.  The author chose to use DocProject to automate the build process, but I suspect that it will work with or without any automation tools for Sandcastle.


Note that I've tested this procedure with success in Visual Studio 2008 standard edition.

Just don't forget to create a new DocProject or DocSite project after applying the Sandcastle patch.  You can use the Import Topics and Settings step in the New Project Wizard to copy over the important stuff from an existing project if you'd like.


On a side note, I think this also about ruins my ContractN project ;).  I've abandoned it anyway, so I'll be doing the honorable thing and will close down the ContractN project on CodePlex at some point (to help keep CodePlex clean - just doin' my part).  I'll continue to host the code on my blog in case anybody's interested in learning how to use Context-Bound Objects, in some form or another.