Create Documentation With Sandcastle Help Builder

This article explains how to create a help documentation in Visual Studio 2017 using SandCastle Help Builder.

First, we need to install SandCastle Help Builder.

  1. Install the latest version of SandCastle Help Builder which you can find from this link.
  2. Now, open your Visual Studio and your project and follow the below steps to create help documentation.

Creating Documentation with Sandcastle

Many of us wonder why XML styled comment summary is used for top of the class, properties, and method. These XML comments are different from traditional comments. These comments are used to generate XML files at compile time.

Summary - This tab provides a short description about type or member.
Param      - This tag provides a description about parameter.
Returns    - This tag provides description about return type of method.
  1. /// <summary>  
  2. /// Addition of Two integer number  
  3. /// </summary>  
  4. /// <param name="a">Fisrt integer number</param>  
  5. /// <param name="b">Secon integer number</param>  
  6. /// <returns>Addition of Two number a + b</returns>  
  7. ///   
  8. public static double Addition(int a, int b)  
  9. {  
  10.     return a + b;  
  11. }  
Let’s document our code with XML comment. These comments are special because it can be processed by the compiler to generate XML file at the compile time. These XML comments are used to produce external documentation.

Please follow the below steps to generate technical help document using SandCastle for the project.

SharePoint
Step 1

Go to class library project properties, click on project properties, and from the next screen, select Build option and then check the checkbox for XML document file.

SharePoint  

SharePoint
 
Step 2

Give an appropriate path for XML file wherever you want to keep it. Here, I have given the default path which will create a file under the bin\debug folder.

step 3

Build the solution and check folder after the build is done. It will create an XML file for all classes, properties, and methods.

  • Snippet 1 - Build the solution once build is succeeded.
  • Snippet 2 - Open the folder in file explore for your XML file.
  • Snippet 3 - Click on XML file.
  • Snippet 4 - Run XML. The output you can see in the browser.
 SharePoint

Step 4

Go to Start menu and select Sandcastle Help Builder and click on Sandcastle Help File Builder GUI. You will be able to see File builder application opened.

Click on "Start a brand new project" and it will give you an option for where to save this document. Select or create the new folder where you want to generate new help document.

Look at the below snippet which will help you to create a new project.

 SharePoint

SharePoint

Step 5

In the below snippet, I have highlighted it with orange.

  • Go to Help File option; then you can:
    • Give Help title: Title for your help documenT
    • Help File Name: Name of your document
    • Copyright notice URL: Copyright URL for your help document
    • Copyright notice Text: Copyright Text for your help document

  • Go to Path option

You can specify the path for your help document where your document will generate.

SharePoint  

Step 6

Go to project Explorer and add your dll file to the documentation sources.

SharePoint
 
Once you add your dll, the XML file is automatically generated.
 
SharePoint  

Step 7

Now, we are done. Now, we need to build the project and it will generate the help document at the specified folder path.

SharePoint  
 
Step 8

That’s it. We are done with all the things which are required to generate help documents. Now, click on the document. You will see that our document is ready. Just look at the last two snippets, we are able to see our class with help. 

SharePoint
 
SharePoint
 
SharePoint  
 
Note
I have attached the source code which I have used for this article.