| Developer(s) | Microsoft |
|---|---|
| Initial release | 2006 |
| Stable release | 2.6.10621.1 / June 23, 2010 |
| Repository | github |
| Written in | C# |
| Operating system | Microsoft Windows |
| Platform | .NET Framework |
| Type | Documentation generator |
| License | Microsoft Public License |
| Website | ewsoftware |
Sandcastle is a documentation generator from Microsoft. It automatically produces MSDN-style code 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 user documentation from Microsoft Assistance Markup Language (MAML) with the same look and feel as reference documentation.
Sandcastle is a set of command line programs, configuration files, build components and XSLT 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 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 the corresponding computer program.
Sandcastle currently features a lightweight 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. [1]
The Visual Studio SDKs for 2005 and 2008 include older CTP versions of Sandcastle, [2] although the latest release is available on GitHub.
Sandcastle consists of several programs, not all of which are used in the typical help build process. Commonly used tools are listed below.
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 produces XML-based HTML files in a chosen presentation style. (This does not mean, however, that the files are XHTML-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.
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).
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.
The Sandcastle application was developed by Microsoft 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 [3] [4] 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 [5] 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 [6] 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". [7] On July 2 the project returned to CodePlex and the source code was published. [8]
In computing, the term Extensible Stylesheet Language (XSL) is used to refer to a family of languages used to transform and render XML documents.
XSLT 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 subsequently be converted to other formats, such as PDF, PostScript and PNG. Support for JSON and plain-text transformation was added in later updates to the XSLT 1.0 specification.
DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software, but it can be used for any other sort of documentation.
The Document Style Semantics and Specification Language (DSSSL) is an international standard developed to provide stylesheets for SGML documents.
XSL-FO is a markup language for XML document formatting that is most often used to generate PDF files. XSL-FO is part of XSL, a set of W3C technologies designed for the transformation and formatting of XML data. The other parts of XSL are XSLT and XPath. Version 1.1 of XSL-FO was published in 2006.
A Help Authoring Tool or HAT is a software program used by technical writers to create online help systems.
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 makes up the Assistance Platform on Windows Vista.
HeaderDoc is a documentation generator developed and maintained by Apple Inc. Using specially commented source code files as input, HeaderDoc generates documentation for the code in HTML or XML format. Syntax for HeaderDoc comment tags is largely similar to, and as of HeaderDoc version 8, supportive of Javadoc tags. HeaderDoc 8.7 and later also provides partial support for many Doxygen tags. Apple's HeaderDoc project is free, open source software distributed under the Apple Public Source License.
In computing, the two primary stylesheet languages are Cascading Style Sheets (CSS) and the Extensible Stylesheet Language (XSL). While they are both called stylesheet languages, they have very different purposes and ways of going about their tasks.
The Oxygen XML Editor is a multi-platform XML editor, XSLT/XQuery debugger and profiler with Unicode support. It is a Java application so it can run in Windows, Mac OS X, and Linux. It also has a version that can run as an Eclipse plugin.
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.
Modes:
The DocBook XSL stylesheets are a set of XSLT stylesheets for the XML-based DocBook language.
DITA Open Toolkit (DITA-OT) is an open-source publishing engine for content authored in the Darwin Information Typing Architecture (DITA).
VSdocman is a documentation generator that allows for code commenting and the automatic generation of technical documentation from C# and VB .NET projects. It is directly integrated in Visual Studio as an extension.
HelpNDoc is a Windows-based help authoring tool published by French company IBE Software.
An XML transformation language is a programming language designed specifically to transform an input XML document into an output document which satisfies some specific goal.
Business Intelligence Markup Language (BIML) is a domain-specific XML dialect for defining business intelligence (BI) assets. Biml authored BI assets can currently be used by the BIDS Helper add-on for Microsoft SQL Server Business Intelligence Development Studio (BIDS) and the Varigence Mist integrated development environment; both tools translate Biml metadata into SQL Server Integration Services (SSIS) and SQL Server Analysis Services (SSAS) assets for the Microsoft SQL Server platform. However, emitters can be created to compile Biml for any desired BI platform.
Antenna House Formatter is a proprietary software program that uses either XSL-FO or Cascading Style Sheets (CSS) to convert XML and HTML documents into PDF, SVG, PostScript, XPS, text, and Microsoft Word formats. It supports 30 scripts and over 80 languages.
