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.
Details
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.
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.