Sandcastle is a
documentation generator
A documentation generator is a programming tool that generates software documentation intended for programmers (API documentation) or end users (end-user guide), or both, from a set of source code files, and in some cases, binary files. Some genera ...
from
Microsoft
Microsoft Corporation is an American multinational technology corporation producing computer software, consumer electronics, personal computers, and related services headquartered at the Microsoft Redmond campus located in Redmond, Washing ...
. It automatically produces
MSDN
Microsoft Developer Network (MSDN) was the division of Microsoft responsible for managing the firm's relationship with developers and testers, such as hardware developers interested in the operating system (OS), and software developers developing ...
-style code documentation out of
reflection Reflection or reflexion may refer to:
Science and technology
* Reflection (physics), a common wave phenomenon
** Specular reflection, reflection from a smooth surface
*** Mirror image, a reflection in a mirror or in water
** Signal reflection, in ...
information of
.NET assemblies and
XML
Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...
documentation comments found in the
source code
In computing, source code, or simply code, is any collection of code, with or without comments, written using a human-readable programming language, usually as plain text. The source code of a program is specially designed to facilitate the wo ...
of these assemblies. It can also be used to produce
user documentation
Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in ...
from
Microsoft Assistance Markup Language
Microsoft Assistance Markup Language (Microsoft AML, generally referred to as MAML) is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance ("online help") for the Microsoft Windows Vis ...
(MAML) with the same look and feel as reference documentation.
Overview
Sandcastle is a set of
command line
A command-line interpreter or command-line processor uses a command-line interface (CLI) to receive commands from a user in the form of lines of text. This provides a means of setting parameters for the environment, invoking executables and pro ...
programs, configuration files, build components and
XSLT
XSLT (Extensible Stylesheet Language Transformations) is a language originally designed for transforming XML documents into other XML documents, or other formats such as HTML for web pages, plain text or XSL Formatting Objects, which may subseque ...
files that work together to convert
XML
Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...
-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
The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaScri ...
documentation in one of three built-in presentation styles from .NET assemblies and XML documentation files that are generated by
compiler
In computing, a compiler is a computer program that translates computer code written in one programming language (the ''source'' language) into another language (the ''target'' language). The name "compiler" is primarily used for programs that ...
s. The resulting HTML files are then used as input to tools such as the
HTML Help Workshop to produce compiled help for distribution with the corresponding
computer program
A computer program is a sequence or set of instructions in a programming language for a computer to execute. Computer programs are one component of software, which also includes documentation and other intangible components.
A computer program ...
.
Sandcastle currently features a lightweight
graphical user interface
The GUI ( "UI" by itself is still usually pronounced . or ), graphical user interface, is a form of user interface that allows users to interact with electronic devices through graphical icons and audio indicator such as primary notation, inste ...
(GUI) as an alternative to the
MSBuild
Microsoft Build Engine, or MSBuild, is a set of free and open-source build tools for managed code under the Common Language Infrastructure as well as native C and C++ code. It was first released in 2003 and was a part of .NET Framework. MSBuil ...
project,
batch script
Batch may refer to:
Food and drink
* Batch (alcohol), an alcoholic fruit beverage
* Batch loaf, a type of bread popular in Ireland
* A dialect term for a bread roll used in North Warwickshire, Nuneaton and Coventry, as well as on the Wirra ...
and
Windows PowerShell
PowerShell is a task automation and configuration management program from Microsoft, consisting of a command-line shell and the associated scripting language. Initially a Windows component only, known as Windows PowerShell, it was made open-sourc ...
scripts that are also provided. Several community GUI tools are also available for Sandcastle, providing additional features and simplifying its usage.
The
Visual Studio
Visual Studio is an integrated development environment (IDE) from Microsoft. It is used to develop computer programs including web site, websites, web apps, web services and mobile apps. Visual Studio uses Microsoft software development platfor ...
SDKs for 2005 and 2008 include older CTP versions of Sandcastle, although the latest release is available on
GitHub
GitHub, Inc. () is an Internet hosting service for software development and version control using Git. It provides the distributed version control of Git plus access control, bug tracking, software feature requests, task management, continuous ...
.
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
Common may refer to:
Places
* Common, a townland in County Tyrone, Northern Ireland
* Boston Common, a central public park in Boston, Massachusetts
* Cambridge Common, common land area in Cambridge, Massachusetts
* Clapham Common, originally com ...
(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 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 BuilderDocProject (Visual Studio 2005/2008)PowerShell scriptMSBuild scriptXML Schema Documenter for Sandcastle Help File Builder
Output
Sandcastle produces XML-based HTML files in a chosen presentation style. (This does not mean, however, that the files are
XHTML
Extensible HyperText Markup Language (XHTML) is part of the family of XML markup languages. It mirrors or extends versions of the widely used HyperText Markup Language (HTML), the language in which Web pages are formulated.
While HTML, prior ...
-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
Microsoft Assistance Markup Language (Microsoft AML, generally referred to as MAML) is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance ("online help") for the Microsoft Windows Vis ...
(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 Interface
An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how t ...
s (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.
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 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 (2002) and MSDN Library.
Microsoft Help 2.x is the help engine used in Microsoft Visual ...
).
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
A table of contents, usually headed simply Contents and abbreviated informally as TOC, is a list, usually found on a page before the start of a written work, of its chapter or section titles or brief descriptions with their commencing page number ...
(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.
Background
The Sandcastle application was developed by
Microsoft
Microsoft Corporation is an American multinational technology corporation producing computer software, consumer electronics, personal computers, and related services headquartered at the Microsoft Redmond campus located in Redmond, Washing ...
to create a scalable and performing
documentation generator
A documentation generator is a programming tool that generates software documentation intended for programmers (API documentation) or end users (end-user guide), or both, from a set of source code files, and in some cases, binary files. Some genera ...
for their
API
An application programming interface (API) is a way for two or more computer programs to communicate with each other. It is a type of software interface, offering a service to other pieces of software. A document or standard that describes how ...
documentation. Microsoft released Sandcastle as a Community Technology Preview (
CTP) version in July 2006, a few days before
NDoc
NDoc is a code documentation generator for the Common Language Infrastructure created by Jason Diamond, Jean-Claude Manoli and Kral Ferch. It is licensed under the GNU General Public License.
How it works
NDoc uses two sources to generate docu ...
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
CodePlex was a forge website by Microsoft. While it was active, it allowed shared development of open-source software.
Its features included wiki pages, source control based on Mercurial, TFVC, Subversion or Git, discussion forums, issue trac ...
.
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
GUI
The GUI ( "UI" by itself is still usually pronounced . or ), graphical user interface, is a form of user interface that allows users to interact with electronic devices through graphical icons and audio indicator such as primary notation, inste ...
was present yet, the application did not contain a feature to resolve
GAC
GAC or Gac may refer to:
Companies and organisations
* GAC Group, a Chinese automotive company based in Guangzhou, Guangdong
* GAC Ireland, an Irish bus manufacturer established with Bombardier (1980–1986)
* Games Administration Committee, ...
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.
HTML
The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaScri ...
output of the application is now compatible with
Firefox
Mozilla Firefox, or simply Firefox, is a free and open-source web browser developed by the Mozilla Foundation and its subsidiary, the Mozilla Corporation. It uses the Gecko rendering engine to display web pages, which implements current and ...
. 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
XML
Extensible Markup Language (XML) is a markup language and file format for storing, transmitting, and reconstructing arbitrary data. It defines a set of rules for encoding documents in a format that is both human-readable and machine-readable. T ...
comment tags.
* November 11, 2006 — the November 2006 CTP version was released, along with bug fixes other items being supported are a few
nDoc
NDoc is a code documentation generator for the Common Language Infrastructure created by Jason Diamond, Jean-Claude Manoli and Kral Ferch. It is licensed under the GNU General Public License.
How it works
NDoc uses two sources to generate docu ...
tags, and also transforms support
Firefox
Mozilla Firefox, or simply Firefox, is a free and open-source web browser developed by the Mozilla Foundation and its subsidiary, the Mozilla Corporation. It uses the Gecko rendering engine to display web pages, which implements current and ...
.
* 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
Mozilla Firefox, or simply Firefox, is a free and open-source web browser developed by the Mozilla Foundation and its subsidiary, the Mozilla Corporation. It uses the Gecko rendering engine to display web pages, which implements current and ...
in the VS 2005 style.
* March 6, 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
MSBuild
Microsoft Build Engine, or MSBuild, is a set of free and open-source build tools for managed code under the Common Language Infrastructure as well as native C and C++ code. It was first released in 2003 and was a part of .NET Framework. MSBuil ...
project, a new version of the
Common Compiler Infrastructure
Common may refer to:
Places
* Common, a townland in County Tyrone, Northern Ireland
* Boston Common, a central public park in Boston, Massachusetts
* Cambridge Common, common land area in Cambridge, Massachusetts
* Clapham Common, originally com ...
(CCI) reflection engine, a new presentation style named, "VS
ORCAS
The orca or killer whale (''Orcinus orca'') is a toothed whale belonging to the oceanic dolphin family, of which it is the largest member. It is the only extant species in the genus ''Orcinus'' and is recognizable by its black-and-white pat ...
", 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
The orca or killer whale (''Orcinus orca'') is a toothed whale belonging to the oceanic dolphin family, of which it is the largest member. It is the only extant species in the genus ''Orcinus'' and is recognizable by its black-and-white pat ...
" presentation style to "Hana" to prevent confusion since the Orcas Beta 2 and RTM documentation shipping in
MSDN
Microsoft Developer Network (MSDN) was the division of Microsoft responsible for managing the firm's relationship with developers and testers, such as hardware developers interested in the operating system (OS), and software developers developing ...
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
PowerShell is a task automation and configuration management program from Microsoft, consisting of a command-line shell and the associated scripting language. Initially a Windows component only, known as Windows PowerShell, it was made open-sourc ...
build script, presentation style updates (most notably to the VS 2005 style), and without the
.NET Framework
The .NET Framework (pronounced as "''dot net"'') is a proprietary software framework developed by Microsoft that runs primarily on Microsoft Windows. It was the predominant implementation of the Common Language Infrastructure (CLI) until bein ...
reflection files that were normally included in previous installers.
* October 30, 2007 — the October 2007 CTP version was released, including the
.NET Framework
The .NET Framework (pronounced as "''dot net"'') is a proprietary software framework developed by Microsoft that runs primarily on Microsoft Windows. It was the predominant implementation of the Common Language Infrastructure (CLI) until bein ...
files that were missing from the previous release, a new conceptual documentation build process requiring
Microsoft Assistance Markup Language
Microsoft Assistance Markup Language (Microsoft AML, generally referred to as MAML) is an XML-based markup language developed by the Microsoft User Assistance Platform team to provide user assistance ("online help") for the Microsoft Windows Vis ...
(MAML) topics as input, and also improved
Firefox
Mozilla Firefox, or simply Firefox, is a free and open-source web browser developed by the Mozilla Foundation and its subsidiary, the Mozilla Corporation. It uses the Gecko rendering engine to display web pages, which implements current and ...
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.NET
ASP.NET is an open-source, server-side web-application framework designed for web development to produce dynamic web pages. It was developed by Microsoft to allow programmers to build dynamic web sites, applications and services. The name s ...
website.
See also
*
Comparison of documentation generators
The following tables compare general and technical information for a number of documentation generators. Please see the individual products' articles for further information. Unless otherwise specified in footnotes, comparisons are based on the s ...
References
External links
*
Sandcastle download*
{{Microsoft FOSS
Free and open-source software
Free documentation generators
Free software programmed in C Sharp
Microsoft free software
Microsoft Visual Studio
Software using the MS-PL license
2006 software
Windows-only free software