Sandcastle for Documentation Build

  • Article

Installation and Layout

Sandcastle CTP can be downloaded from https://www.microsoft.com/downloads/details.aspx?FamilyId=E82EA71D-DA89-42EE-A715-696E3A4873B2&displaylang=en

Instructions:

  • Visit the above link to download and install Sandcastle .

  • Sandcastle default installation directory is C:\Program Files\Sandcastle

At the Sandcastle installation location, you will find the following directory structure:

  • Examples: Sources for example build.

  • Presentation: Files used in the production and rendering of topic pages.

    • Art: Image files used in the topics pages.

    • Scripts: Javascript files used in the topics pages.

    • Styles: CSS stylesheet files used in the topic pages.

    • Transforms: XSL transforms used to generate topic pages.

    • Content: Shared content files used to generate topic pages.

    • Confguration: Configuration files for the topic page generation software.

    • Hxs: Templates of files used to generate an HxS package.

    • Chm: Templates of files used to generate a CHM package

  • ProductionTools: Binary executables of Sandcastle components.

  • ProductionTranforms: Various XSL transforms used in the build process (not the topic-generating transforms).

Sandcastle: The Philosophy

The previous version of Sandcastle , used during VS 2005 ship cycle, consisted of a small number of large components that did a large number of jobs. pDoc, for example, collated authored comments and reflection information, generated syntax blocks, and applied XSL transforms to present that information as a topic page. It also generated HXS and CHM definition files for the project containing the topic pages.

The current version of Sandcastle adopts a very different philosophy. It consists of a large number of small components, each of which does one small job in a highly configurable way. While this results in a version that is much more flexible and efficient, it also results in a version with a lot more components and configuration options. Many of these “components” are actually nothing more than an XSLT file that performs a particular job. Some are executables, but their behavior can be changed by changing plug-ins

Sandcastle: The Realization

The center-piece of Sandcastle is a stack of components that acts on each topic. Each component has a job to do. Loading data from a file, applying a transformation to the topic, or saving the topic to a file are some examples of component actions.

The following are the steps used by the build component stack:

  • Load reflection data

  • Load authored comments

  • Execute XSL transform

  • Save the document

The component that controls the build stack is BuildAssembler . To run BuildAssembler , you give it a configuration file that defines the component stack and a manifest file that lists the topics to be built.

In your daily builds, you will experience BuildAssembler as a “heavy-weight” component. It has by far the longest run-time of any of steps in the build process and it has a complex configuration file that allows you to modify every conceivable aspect of the topic build process. Actually, though, BuildAssembler is among the most “light-weight” of all the Sandcastle components. That’s because its only job is to load the components specified in the configuration file and run them for each topic in the manifest.

Small Reference Build

Sandcastle can read authored comments from triple-slash comments embedded in source files. The Sandcastle example illustrates this scenario. Sandcastle by default is installed at c:\Program files\Sandcastle. Open a command prompt and type the following:

cd \Program Files\Sandcastle\Examples

In this directory, you will find only a single C# file called test.cs. Begin by compiling the C# file and extracting the /// comments.

csc /t:library /doc:comments.xml test.cs

This creates not only test.dll, but also comments.xml file that contains the extracted /// comments. The first step in a reference build is to extract data about the APIs to be documented from the managed assemblies containing them. The Sandcastle component for this operation is MRefBuilder . To extract API data from mscorlib.dll, just run:

      MRefBuilder test.dll /out:reflection.org

If you open the reflection.org file that you have just created, you will see that it is an XML file containing data about every API in the assembly.

An approximate description of our documentation model is that we generate a topic page for each API. This description, however, is only approximate, because our documentation model creates additional topic pages that do not correspond to APIs: overload topics, member list topics, etc. On the one hand, these topic pages do contain reflection information, so it would be convenient if elements corresponding to them existed in the reflection information file. On the other hand, the additional topic pages do not actually correspond to APIs defined in the assembly: they come and go as we change our document model.

Sandcastle resolves the tension between the idea that entries in the reflection file should represents APIs and the idea that entries in the reflection file should represent topics in a novel way. MRefBuilder produces one-entry-per-API file that represents assembly information; the developer then applies a series of transforms to produce a one-entry-per-topic file that represents the documentation. Thus when the doc model changes, only the applied transforms need to change; MRefBuilder does not need to be re-compiled.

To apply our documentation model, we execute the following series of XSL transformations.

      XslTransform ..\..\ProductionTransforms\AddOverloads.xsl

          reflection.org |

      XslTransform ..\..\ProductionTransforms\AddRoot.xsl

          /arg:name=test |

      XslTransform ..\..\ProductionTransforms\AddGuidFilenames.xsl

      /out:reflection.xml

If you open the reflection.xml file you will see that its structure is similar to that of the reflection.org file, but it now also contains entries for overload topics and for a root page that lists all namespaces, and that each entry now has an associated file name.

Now that we have a file that contains reflection data for each topic, we are ready to produce a manifest of topics to build. This accomplished via simple transformation of our reflection data file:

XslTransform ..\..\ProductionTransforms\ReflectionToManifest.xsl

          reflection.xml /out:manifest.xml

Now we are ready to actually build our documentation. To create the output directory type the following:

..\copyOutput.bat

Run BuildAssembler using the Sandcastle component stack (The Sandcastle.config file should be copied from C:\Program Files\Sandcastle\Presentation\Configuration to the current directory)

BuildAssembler /config:sandcastle.config manifest.xml

When the build is completed, try opening a file in the Output\html directory and browse through the topics you have created.

Before we package the topics we have created, take a few minutes to open the Sandcastle.config file that defined the component stack for this build and you will observe the following components:

1. Load a skeleton file that defines sections for various kinds of data.

2. Load reflection data for the topic.

3. Load reflection data for the “container” (e.g. namespace) topics.

4. Generate syntax blocks.

5. Load authored comments.

6. Load authored comments and reflection data for the “element” (e.g. member) topics.

7. Apply an XSL transform to generate HTML.

8. Resolve shared content references.

9. Resolve reference links.

10. Save the result.

Each step is done by one build component (occasionally a few build components). By changing the configuration information passed to the components, you customize the build. Most of the work in defining a new project will consist of appropriately customizing the BuildAssembler configuration file.