Sandcastle tutorial: automating your documentation
-
Upload
kwork-innovaatiot -
Category
Software
-
view
52 -
download
3
Transcript of 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 [email protected]
Antti ”Andy” Törrö[email protected]