SandCastle
Encyclopedia
Sandcastle is a documentation generator
from Microsoft
that automatically produces MSDN style reference documentation out of reflection information of .NET
assemblies
and XML
documentation comments found in the source code
of these assemblies. It can also be used to produce compiled user documentation from Microsoft Assistance Markup Language (MAML)
with the same look and feel as reference documentation.
transformation files that work together to convert XML
-based documentation into help topics that are fit for viewing in a help system. Sandcastle is typically used to automatically generate web-ready, XML-compliant HTML documentation in one of three built-in presentation styles from .NET assemblies and XML documentation files that are generated by code compilers
. The resulting HTML files are then used as input to tools such as the HTML Help Workshop to produce compiled help for distribution with a software application
.
Sandcastle currently features a light weight Graphical User Interface
(GUI) as an alternative to the MSBuild
project, batch script and Windows PowerShell scripts that are also provided. Several community GUI tools are also available for Sandcastle, providing additional features and simplifying its usage.
The Visual Studio SDKs for 2005 and 2008 include older CTP versions of Sandcastle , although the latest release is available on CodePlex.
compliant.) The HTML is defined by XSL transformation files that are included in the particular presentation style being used. A build normally uses only one presentation style at a time.
The HTML files that Sandcastle produces are either conceptual (user) documentation, being the result of a transformation from Microsoft Assistance Markup Language (MAML)
topics, or they are reference documentation, which is automatically generated from reflection data and XML documentation comments. These two different types of HTML output share the same presentation style and may be compiled together to produce mixed user/reference documentation.
The processes for building conceptual documentation and reference documentation are similar, with one of the main differences being that conceptual documentation does not require the MRefBuilder program to be used.
Conceptual documentation consists of topics written using a MAML document type schema such as how to, walk-through, troubleshooting and several others. Sandcastle provides a conceptual build component stack (conceptual.config) that resolves shared content and links, and uses XSL files to transform MAML elements into HTML.
Reference documentation is generated automatically for managed Application Programming Interfaces (APIs)
from reflection data and XML documentation comments. A "doc model" XSL transformation, provided by the chosen presentation style, is applied to define the files that will be generated. Sandcastle provides a reference build component stack (sandcastle.config) that builds in-memory indexes of the data, resolves shared content and links, and uses XSL to generate the final HTML output.
.
For example, the typical Help 1.x build process starts by running MrefBuilder.exe to produce an XML reflection file for one or more assemblies. The reflection file is then processed by the XslTransform.exe tool multiple times to apply various XSL transformations that add data such as a "doc model" and optional version information. Next, an XML-based topic manifest is generated and used by the BuildAssembler.exe program, which generates HTML topic files from the reflection data and XML documentation comments. An XML-based table of contents (TOC)
file is generated and used by CHMBuilder.exe, along with the HTML files produced by BuildAssembler, to generate HTML Help Workshop project, index and TOC files. Finally, the HTML Help workshop is used to generate a compiled help file (.chm).
Some tools are used multiple times during a single build, like XslTransform and BuildAssembler. Depending upon the requirements, other tools and XSL transformations may be used at various stages during the process to modify Sandcastle's output.
to create a scalable and performing documentation generator
for their API
documentation. Microsoft released Sandcastle as a Community Technology Preview (CTP) version in July 2006, a few days before NDoc
was declared dead The author of NDoc, Kevin Downs, cited in an email sent through his mailing list reasons for discontinuing development of his popular tool as a lack of community support, both financially and as development contributions, an automated mail-bomb attack on his public email address and the NDoc2 mailing list address, and also his impression that Sandcastle "will become the de-facto standard and that NDoc will slowly become a stagnant side-water."
Sandcastle averaged 217 downloads per day during the month of September 2010, making it one of the top 25 most downloaded projects on CodePlex.
On June 6, 2008 the SandCastle project was removed from CodePlex website after a discussion thread on the CodePlex site pointed out that source code was not available; despite CodePlex requiring this and the SandCastle project being touted as "open source".. On July 2 the project returned to CodePlex and the source code was published.
Documentation generator
A documentation generator is a programming tool that generates documentation intended for programmers or end users , or both, from a set of specially commented source code files, and in some cases, binary files....
from Microsoft
Microsoft
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
that automatically produces MSDN style reference documentation out of reflection information of .NET
.NET Framework
The .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...
assemblies
.NET assembly
In the .NET framework, an assembly is a compiled code library used for deployment, versioning, and security. There are two types: process assemblies and library assemblies . A process assembly represents a process that will use classes defined in library assemblies...
and XML
XML
Extensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....
documentation comments found in the source code
Source code
In computer science, source code is text written using the format and syntax of the programming language that it is being written in. Such a language is specially designed to facilitate the work of computer programmers, who specify the actions to be performed by a computer mostly by writing source...
of these assemblies. It can also be used to produce compiled user documentation from Microsoft Assistance Markup Language (MAML)
Microsoft Assistance Markup Language
Microsoft Assistance Markup Language is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance for the Microsoft Windows Vista operating system. It is somewhat of a departure from all previous types of user assistance for Windows operating...
with the same look and feel as reference documentation.
Overview
Sandcastle is a set of command line programs, configuration files, build components and XSLTXSLT
XSLT is a declarative, XML-based language used for the transformation of XML documents. The original document is not changed; rather, a new document is created based on the content of an existing one. The new document may be serialized by the processor in standard XML syntax or in another format,...
transformation files that work together to convert XML
Extensible Markup Language
Extensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....
-based documentation into help topics that are fit for viewing in a help system. Sandcastle is typically used to automatically generate web-ready, XML-compliant HTML documentation in one of three built-in presentation styles from .NET assemblies and XML documentation files that are generated by code compilers
Compiler
A compiler is a computer program that transforms source code written in a programming language into another computer language...
. The resulting HTML files are then used as input to tools such as the HTML Help Workshop to produce compiled help for distribution with a software application
Application software
Application software, also known as an application or an "app", is computer software designed to help the user to perform specific tasks. Examples include enterprise software, accounting software, office suites, graphics software and media players. Many application programs deal principally with...
.
Sandcastle currently features a light weight Graphical User Interface
Graphical user interface
In computing, a graphical user interface is a type of user interface that allows users to interact with electronic devices with images rather than text commands. GUIs can be used in computers, hand-held devices such as MP3 players, portable media players or gaming devices, household appliances and...
(GUI) as an alternative to the MSBuild
MSBuild
MSBuild is a Microsoft build platform typically used in conjunction with Visual Studio. MSBuild version 2.0 is part of .NET Framework 2.0 and works together with Visual Studio 2005...
project, batch script and Windows PowerShell scripts that are also provided. Several community GUI tools are also available for Sandcastle, providing additional features and simplifying its usage.
The Visual Studio SDKs for 2005 and 2008 include older CTP versions of Sandcastle , although the latest release is available on CodePlex.
Sandcastle tools
Sandcastle consists of several programs, not all of which are used in the typical help build process. Commonly used tools are listed below.- MrefBuilder uses Common Compiler Infrastructure (CCI) to reflect against managed assemblies and generate an output file.
- XslTransform applies XSL transformations to an XML file. Typically, the specified input file is or derives from a file that is generated by MRefBuilder.
- BuildAssembler executes a build component stack, once for each topic defined in an XML manifest. A build component stack is defined in an XML file with a .config extension. Sandcastle provides several build components that are used in build component stacks to perform tasks such as generating in-memory data indexes, resolving links, including shared content, executing XSL transformations and saving the final output to a file.
Community tools
Because in its current state Sandcastle by itself is rather complex to use, people have come up with tools and scripts that can automate the task for them. This section contains a list of such tools and scripts.- Sandcastle Help File Builder
- DocProject (Visual Studio 2005/2008)
- Sandcastle Helper
- Batch file
- PowerShell script
- MSBuild script
- Sandcastle Visual Studio Add-In
- XML Schema Documenter for Sandcastle Help File Builder
- An example of how Sandcastle can be used with NAnt.
Output
Sandcastle produces XML-based HTML files in a chosen presentation style. (This does not mean, however, that the files are XHTMLXHTML
XHTML is a family of XML markup languages that mirror or extend versions of the widely-used Hypertext Markup Language , the language in which web pages are written....
compliant.) The HTML is defined by XSL transformation files that are included in the particular presentation style being used. A build normally uses only one presentation style at a time.
The HTML files that Sandcastle produces are either conceptual (user) documentation, being the result of a transformation from Microsoft Assistance Markup Language (MAML)
Microsoft Assistance Markup Language
Microsoft Assistance Markup Language is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance for the Microsoft Windows Vista operating system. It is somewhat of a departure from all previous types of user assistance for Windows operating...
topics, or they are reference documentation, which is automatically generated from reflection data and XML documentation comments. These two different types of HTML output share the same presentation style and may be compiled together to produce mixed user/reference documentation.
The processes for building conceptual documentation and reference documentation are similar, with one of the main differences being that conceptual documentation does not require the MRefBuilder program to be used.
Conceptual documentation consists of topics written using a MAML document type schema such as how to, walk-through, troubleshooting and several others. Sandcastle provides a conceptual build component stack (conceptual.config) that resolves shared content and links, and uses XSL files to transform MAML elements into HTML.
Reference documentation is generated automatically for managed Application Programming Interfaces (APIs)
Application programming interface
An application programming interface is a source code based specification intended to be used as an interface by software components to communicate with each other...
from reflection data and XML documentation comments. A "doc model" XSL transformation, provided by the chosen presentation style, is applied to define the files that will be generated. Sandcastle provides a reference build component stack (sandcastle.config) that builds in-memory indexes of the data, resolves shared content and links, and uses XSL to generate the final HTML output.
Compiled help
Sandcastle does not produce compiled help output itself; although, the HTML files that it produces can be used as input to HTML help compilers such as the HTML Help Workshop and Microsoft Help 2Microsoft Help 2
Microsoft Help 2.x is a proprietary format for online help files, developed by Microsoft and first released in 2001 as a help system for Visual Studio .NET and MSDN Library....
.
For example, the typical Help 1.x build process starts by running MrefBuilder.exe to produce an XML reflection file for one or more assemblies. The reflection file is then processed by the XslTransform.exe tool multiple times to apply various XSL transformations that add data such as a "doc model" and optional version information. Next, an XML-based topic manifest is generated and used by the BuildAssembler.exe program, which generates HTML topic files from the reflection data and XML documentation comments. An XML-based table of contents (TOC)
Table of contents
A table of contents, usually headed simply "Contents" and abbreviated informally as TOC, is a list of the parts of a book or document organized in the order in which the parts appear...
file is generated and used by CHMBuilder.exe, along with the HTML files produced by BuildAssembler, to generate HTML Help Workshop project, index and TOC files. Finally, the HTML Help workshop is used to generate a compiled help file (.chm).
Some tools are used multiple times during a single build, like XslTransform and BuildAssembler. Depending upon the requirements, other tools and XSL transformations may be used at various stages during the process to modify Sandcastle's output.
Background
The Sandcastle application was developed by MicrosoftMicrosoft
Microsoft Corporation is an American public multinational corporation headquartered in Redmond, Washington, USA that develops, manufactures, licenses, and supports a wide range of products and services predominantly related to computing through its various product divisions...
to create a scalable and performing documentation generator
Documentation generator
A documentation generator is a programming tool that generates documentation intended for programmers or end users , or both, from a set of specially commented source code files, and in some cases, binary files....
for their API
Application programming interface
An application programming interface is a source code based specification intended to be used as an interface by software components to communicate with each other...
documentation. Microsoft released Sandcastle as a Community Technology Preview (CTP) version in July 2006, a few days before NDoc
NDoc
NDoc is a code documentation generator for the Common Language Infrastructure. It is licensed under the GNU General Public License.- How it works :...
was declared dead The author of NDoc, Kevin Downs, cited in an email sent through his mailing list reasons for discontinuing development of his popular tool as a lack of community support, both financially and as development contributions, an automated mail-bomb attack on his public email address and the NDoc2 mailing list address, and also his impression that Sandcastle "will become the de-facto standard and that NDoc will slowly become a stagnant side-water."
Sandcastle averaged 217 downloads per day during the month of September 2010, making it one of the top 25 most downloaded projects on CodePlex.
On June 6, 2008 the SandCastle project was removed from CodePlex website after a discussion thread on the CodePlex site pointed out that source code was not available; despite CodePlex requiring this and the SandCastle project being touted as "open source".. On July 2 the project returned to CodePlex and the source code was published.
History
- July 29, 2006 the July 2006 CTP version was released, this version mainly focused on performance and scalability. No GUIGuiGui or guee is a generic term to refer to grilled dishes in Korean cuisine. These most commonly have meat or fish as their primary ingredient, but may in some cases also comprise grilled vegetables or other vegetarian ingredients. The term derives from the verb, "gupda" in Korean, which literally...
was present yet, the application did not contain a feature to resolve GACGlobal Assembly CacheThe Global Assembly Cache or GAC is a machine-wide .NET assemblies cache for Microsoft's CLR platform. The approach of having a specially controlled central repository addresses the shared library concept and helps to avoid pitfalls of other solutions that led to drawbacks like DLL hell.-...
DLLs yet.
- August 28, 2006 the August 2006 CTP version was released, the bugs fixed in this release seem to primarily for fixing crashes of the application. HTMLHTMLHyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....
output of the application is now compatible with Firefox. Some changes were made to the command line interface.
- October 1, 2006 the September 2006 CTP version was released, bug fixes primarily seem to focus on fixing bugs in the output, and adding better support for some XMLXMLExtensible Markup Language is a set of rules for encoding documents in machine-readable form. It is defined in the XML 1.0 Specification produced by the W3C, and several other related specifications, all gratis open standards....
comment tags.
- November 11, 2006 the November 2006 CTP version was released, along with bug fixes other items being supported are a few nDocNDocNDoc is a code documentation generator for the Common Language Infrastructure. It is licensed under the GNU General Public License.- How it works :...
tags, and also transforms support Firefox.
- December 10, 2006 the December 2006 CTP version was released, providing a DXROOT environment variable used by configuration files, an API "ripping" feature, pass-through HTML, and presentation updates that included support for Firefox in the VS 2005 style.
- March 06, 2007 the March 2007 CTP version was released, adding 4 new and removing 3 XSL transformations, a batch build script and performance improvements.
- March 17, 2007 the March 2007 CTP Technical Refresh version was released, fixing the "ripping" feature and a utility bug, and including a file that was missing from the previously released installer.
- June 19, 2007 the June 2007 CTP version was released, providing an MSBuildMSBuildMSBuild is a Microsoft build platform typically used in conjunction with Visual Studio. MSBuild version 2.0 is part of .NET Framework 2.0 and works together with Visual Studio 2005...
project, a new version of the Common Compiler Infrastructure (CCI) reflection engine, a new presentation style named, "VS ORCAS", a new build component, new executable utilities, and several other enhancements.
- June 27, 2007 the June 2007 CTP Refresh version was released, renaming the previously released "VS ORCAS" presentation style to "Hana" to prevent confusion since the Orcas Beta 2 and RTM documentation shipping in MSDN was going to continue to be built in the VS 2005 presentation style.
- October 1, 2007 the September 2007 CTP version was released, with the first appearance of the CHMBuilder, VersionBuilder and DBCSFix tools, a Windows PowerShell build script, presentation style updates (most notably to the VS 2005 style), and without the .NET Framework.NET FrameworkThe .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...
reflection files that were normally included in previous installers.
- October 30, 2007 the October 2007 CTP version was released, including the .NET Framework.NET FrameworkThe .NET Framework is a software framework that runs primarily on Microsoft Windows. It includes a large library and supports several programming languages which allows language interoperability...
files that were missing from the previous release, a new conceptual documentation build process requiring Microsoft Assistance Markup Language (MAML)Microsoft Assistance Markup LanguageMicrosoft Assistance Markup Language is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance for the Microsoft Windows Vista operating system. It is somewhat of a departure from all previous types of user assistance for Windows operating...
topics as input, and also improved Firefox support.
- January 16, 2008 the Sandcastle 2.4.10115 version was released, being the first official non-CTP version of Sandcastle released to the web (RTW). An example graphical user interface (GUI) was provided, including an XSL transformation for Script# and the option to output an ASP.NETASP.NETASP.NET is a Web application framework developed and marketed by Microsoft to allow programmers to build dynamic Web sites, Web applications and Web services. It was first released in January 2002 with version 1.0 of the .NET Framework, and is the successor to Microsoft's Active Server Pages ...
website.
See also
- NDocNDocNDoc is a code documentation generator for the Common Language Infrastructure. It is licensed under the GNU General Public License.- How it works :...
- Doc-O-Matic
- VSdocmanVSdocmanVSdocman allows commenting and the automatic generation of technical documentation from VB .NET and C# source code files.VSdocman parses the Visual Studio projects and automatically creates the table of contents, index, API and custom topics, cross-references, IntelliSense and F1 context-sensitive...
- MSBuildMSBuildMSBuild is a Microsoft build platform typically used in conjunction with Visual Studio. MSBuild version 2.0 is part of .NET Framework 2.0 and works together with Visual Studio 2005...
- Windows PowerShellWindows PowerShellWindows PowerShell is Microsoft's task automation framework, consisting of a command-line shell and associated scripting language built on top of, and integrated with the .NET Framework...
- DoxygenDoxygenDoxygen is a documentation generator for multiple programming languages.Doxygen is a tool for writing software reference documentation. The documentation is written within code, and is thus relatively easy to keep up to date...