Sandcastle and SHFB

This article is an article about working with Sandcastle and SHFB , in order not to forget yourself and tell others.

4 years have passed since the last article on Sandcastle ( “Creating Documentation in .NET” ), so it's time to refresh some points of this documentation utility.

When there was a question about the documentation on our project, the choice was mostly between Doxygen (which was already used in the project) and Sandcastle (which was used before by the customer). In the end, the choice fell on Sandcastle, because It was recommended by the customer himself, generated similar documentation visually, unlike Doxygen, as well as integration with Help & Manual (integration was not used as a result).

For those who are too lazy to google, but it's interesting to see a list of other tools for documentation, here's a good list: stackoverflow.com/a/14420174
')
In a simplified form, the task itself was the generation of documentation in the form of a ".chm" file and help on the site. As an example, there will be a small project from the library with a pair of documented classes and the Sandcastle project itself (link to github: github.com/misiam/Sandcastle-Sample ).

Installation

First you need to install Sandcastle, or rather, Sandcastle Help File Builder (SHFB). This is a continuation of the project, which is viciously abandoned by the firm M $ and carefully forknut Eric Woodruff. Downloading from here: shfb.codeplex.com/releases/view/121365

The chm-compiler and the plug-in for VS2012 and VS2013 were important to me first of all. In addition, Sandcastle Help File Builder itself is actually installed, it is an application that allows you to use the interface, rather than writing everything into xml files. With the exception of the text editing toolbar (bold, italics, etc.), I didn’t find any differences between SHFB and the studio plugin, and the studio also offers auto-compiler with intelisens, so I gradually developed the development to it.

Project Setup

When everything is installed, you can add a project to the solution. A “Documentation / Sandcastle Help File Builder Project” appeared in the studio, select it, add “Documentation Sources” (a link to the project we are documenting), turn on the “XML documentation file” in the project, and launch the build. Go to the folder / bin ... and find nothing there. The thing is that by default Sandcastle creates files in the \ Help folder in the project folder.

To avoid this, go to the project properties -> Path -> “Help content output path” and change to something more familiar, for example, to “bin \ Help \”. After the build, you can see LastBuild.log (created by default in the output folder) and the chm file. Do not pay attention to the appearance and warnings.

Now the help is created in the folder in which we wanted, but the help should also be opened from the webcam, and chm fully supports only explorer, the rest of browsers will, at best, open such a help with the appropriate plugin. It's easier to generate the Website: project properties -> Build -> turn on the “Website (HTML / ASP.NET)" (in fact, there is also php there, you can delete it in the post build event. And one more remark: build events can not to work at assembly from studio and SHFB - collect through msbuild).

As soon as you add a Website, you will be able to detect the following problem: both helpers are in the same folder. Beloved, uncomfortable, and not comme il faut. Go to the project properties -> Plug-Ins -> Output Deployment -> Add. Here we indicate the relative paths for copying.


It remains quite a bit to bring the project in order.

In the Website / html directory, all files of the [GUID] .htm type. To fix this, go to the project properties -> Help File and change the “Topic file naming method” property from “GUID” to a more readable “Member name”. Now the address in the browser will reflect the page on which the user is located.

In those places where there is no documentation, the red warning labels “Missing documentation for ...” appear in the help.



Such inscriptions are convenient in development, but completely unacceptable in the finished documentation. To remove them, go to the project properties -> Missing Tags and choose which elements should not display messages if they have no documentation. Also currently used languages ​​are C #, VB, C ++, F #. Project properties -> Help File -> Syntax Filters and select only those languages ​​that are necessary.

Create a couple of pages.

To begin, delete the Version History folder with all its contents and the Welcome.aml page from the project. The documentation structure is built in the ContentLayout.content file, so you have to clean this file as well.

In most cases, when creating a new documentation page, you have to choose the “Conceptual” type (there are many types and you can talk about them for a long time). When creating a new page, you need to add it to ContentLayout. The possibilities of configuring static pages with respect to the generated code and each other are very large, you can make a topic tree the way you want.

Documentation pages link to each other using a topic ID. It can be found at the top of the page in the corresponding attribute.

Example:

<link xlink:href="b2ac2359-2794-4644-b900-297937ffeaae" /> 

Problems begin when it is necessary to refer to the generated pages. In this case, Sandcastle disagrees with the syntax used in the <see /> meta tags and uses its own:

 <codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.ConstructorsSamples.#ctor(System.String,System.Int32)</codeEntityReference> <codeEntityReference qualifyHint="true">M:SandcastleSample.Samples.MethodsSamples.MethodWithRefParameter(System.String,System.String@)</codeEntityReference> 

qualifyHint is set to “true” if you want to show the method signature.


The list is large, and such things just have to know, there's nothing you can do.
Although you can enable the warnings "Missing documentation ..." and there you can see in what form Sandcastle expects the name of the method.

Tips and tricks

• There are different interface templates: vs2013, vs2010, vs2005, Hana, Prototype. It is worth trying at least vs2013 and vs2010 - both of them are not deprecated, and their behavior is different. For example, in vs2013 after the search, the topic opens in a new tab, which was critical on our project. It is also worth noting that the Webhelp can be referred to both Index.aspx and index.html. Part of the functionality in the second case will not be available (for example, search).
• To add a description to Namespace, include the following class in it:
  

   ///<summary>Namespace summary</summary> ///<include file='_Namespace.xml' path='Documentation/*' /> internal class NamespaceDoc { //EMPTY } 

  
  The same can be done through Sandcastle.
  
• To add a description to the topic of the generated overloaded method, use the tag:
  

    /// <summary> /// Go to overload <see cref="O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload"/> /// <example> /// <para>To link to both overloads use 'O': <code>O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload</code></para> /// </example> /// </summary> /// <overloads> /// <para>'overloads' tag used in Sandcastle to put some additional inforation to "Ovetrload methods" page in the documentation.</para> /// </overloads> /// <param name="param"></param> public void MethodWithOverload(string param) { } 

  
  VisualStudio will leave this tag unattended, but Sandcastle will add its contents to the documentation.
  
  A table of such tags can be found at: Sandcastle's XML Documentation Comments ;
  
  Once again the link to the project with examples on github .