A Guide to Sandcastle - Part 2 - Customizing the build process [Build]

The default documentation build carries some basic options that might be enough for most cases. However, offers much more than it is offered by default. In today's article I am covering some of the major customization options that are available. Of course, covering each one of them wouldn't make any sense due to the simple fact that a lot of them are self-explanatory and have a pretty decent description on the bottom of the property page.

As I mentioned in the previous article, I am covering the building process in the context of the Sandcastle Help File Builder.

Launch SHFB once again and reference some simple .NET assemblies. These can be any assemblies you want - from DLLs to full-fledged applications. The more complex - the better, since you will have a better understanding of what each option I am talking about does.

BuildLogFile

I am going to start with BuildLogFile - not a lot of people fully appreciate the benefit of having a log. And before one goes looking for external help, looking at the log file is the first thing that should be done.

By default, the log file is stored in the Help folder - right where the actual documentation is compiled. You can, however, change the path to the log file. If you set the IsFixedPath property to True and set a path, it means that the path you are using is an absolute one. If IsFixedPath is set to False then the path to the log file is considered relative.

From my own experience I can say this - since I started using Sandcastle, the log file is the main helper in a lot of situations - of course you can view the build data directly in the Build Output tab, but when it comes to analyzing some additional data (e.g. warnings), a local resource is priceless, especially since it contains XML-formatted data - I can easily build a custom log viewer on top of the existing toolset for better tracking.

CleanIntermediates

While building the documentation tree, Sandcastle is creating a set of secondary files that are used to store Reflection data, documentation structure as well as un-compiled data files (e.g. separate HTML files not bound under a single CHM file).

This particular set of files is not extremely useful unless you want to look under the hood of the actual build process and see what data is used to build a documentation library based on the given assembly (or set of assemblies).

ComponentConfigurations

This is the extensibility point for SHFB that allows the developer (or the person who managed the process) to apply custom documentation formatters and general appearance of the generated help files. For example, via this layer it is possible to add custom images to a document (or a limited subset of those), change the way code is displayed in the context of a specific style and even generate additional files related to the assemblies loaded for analysis.

Build components are not a mandatory part of the build process and can be easily added or eliminated.

The default components are just the tip of the iceberg. You can create your own or download existing ones to improve the overall experience. Here are some resources worth checking:

• Standalone Components and Tools v1.9.1.0
• Drawbridge (diagram integration)

DisableCodeBlockComponent

Let's say that in your application you are using the <code> tag in the context of an example:

/// <example>
/// This is an example.
/// <code>
/// SampleCode code = new SampleCode();
/// code.ExecuteAction();
/// </code>
/// </example>

The Code Block Build Component allows the developer to customize the sample code box. For example, to colorize the content or include line numbers. The DisableCodeBlockComponent property was designed to allow a quick switch between modes for the component without the need to go to the build components configuration dialog. The plain result looks like this:

Make sure that the managed assembly passed as a documentation source has an associated XML documentation file for this option to work correctly.

HelpFileFormat

Here is where you can select the way you want the information to be displayed. Generally, there are 4 formats available:

HtmlHelp1 - The very basic (and the oldest) help format. A generated CHM (Compiled HTML) file will contain the tree structure of the namespaces included in the build. It is easy to use and it is quite portable. Also a great benefit related to it is that it can work on older version of Windows (even where the assembly itself might not work).

MSHelp2 - The updated help format used in Visual Studio versions 2002 to 2008. It is not as portable as one would want to due to some platform limitations. The Visual Studio 2008 SDK is required to compile in this format and if you only have Visual Studio 2010 installed, you might want to either skip this format or install the SDK separately.

MSHelpViewer1 - The format used in Visual Studio 2010 (and most likely for the next versions too). It integrates directly in the new Help Viewer application and is installed as a separate package. Can be managed only internally and is not really portable (as in click-and-view). However, to facilitate the addition and removal process, there are two pre-built scripts available for distribution (specifically targeting a help package).

Website - The universal platform-independent format that can be viewed in any JavaScript-enabled browser. Can be used to build a web-based MSDN-like library.