sandcastle tutorial: automating your documentation

Sandcastle Tutorial

What is Sandcastle

Sandcastle is an open source automation tool for code documentation, initially developed by Microsoft, currently continued by the community on the GitHub platform.

Sandcastle works by parsing the XML comments out of program assemblies (.exe, .dll, .csproj, .sln) and formatting them in order to form MSDN-like documentation pages.

The framework is powerful and comes with multiple configuration options, giving precise control and big freedom in terms of customization.

Introduction

What is Sandcastle

Sandcastle is best used when working with large .NET assemblies, giving clear and easy solution for organizing and indexing your documentation.

Sandcastle is very strict about your comment structure, so it incentivizes correct formatting and cleaner approach to documentation.

Usage

Installation

To begin installation of Sandcastle, you must go to its official GitHub page.

LINK

In Readme section, follow the Get the current release link.

Download the zipped installer file, extract it to desired location and launch the SandcastleInstaller.exe file.

Installation

Note: for the installation to succeed, you need to have the minimum required .NET Framework version (as of Feb 2017, the version required is 4.5)

You can proceed with the installation by following the instructions. Installer will suggest optional packages, such as HTML Help 1 Compiler or SHFB Visual Studio Package. Customize the process according to your own needs (e.g. not everyone needs to compile .chm files, so HTML Help 1 Compiler will be redundant).

Sandcastle Help File Builder and Tools is the basic recommended installation.

Getting started

1. File -> New ProjectPick a folder in which the project should be containedName it-> Save2. Choose which formats you want to build (Website recommended)3. Choose which Framework version you are building (newest available recommended)4. In Visual Studio, create an XML documentation file (right click on your project -> Properties -> Build -> check “XML documentation file”)5. Change more advanced setting according to your wishes6. Documentation -> Build Project

Moving forward

Refer to the official Sandcastle documentation for more information.

Refer to the FAQ in case of build errors.

For more programming resources, see www.kwork.me

Do you need help with your software or development? Contact us at www.kwork.me

Kwork Innovationswww.kwork.fiinfo@kwork.me

Antti ”Andy” Törrönenantti@kwork.me