Sandcastle and SHFB
This article is an article about working with Sandcastle and SHFB , so as not to forget yourself and tell others. Four years have passed since the last Sandcastle article ( “Creating Documentation in .NET” ), so it’s time to refresh some points of this documentation utility.
When the question arose about the documentation on our project, the choice was mostly between Doxygen (which was already used in the project) and Sandcastle (which was previously used by the customer). As a result, the choice fell on Sandcastle, as it was recommended by the customer himself, generated similar visual documentation, unlike Doxygen, as well as integration with Help & Manual (the 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 was to generate documentation in the form of a ".chm" file and a help on the site. As an example, there will be a small project from a library with a couple of documented classes and the Sandcastle project itself (link to github: github.com/misiam/Sandcastle-Sample ).
Installation
First of all, you need to install Sandcastle, or rather, Sandcastle Help File Builder (SHFB). This is a continuation of the project, which is viciously abandoned by M $ and carefully forked by Eric Woodruff. Download from here: shfb.codeplex.com/releases/view/121365 The
chm compiler and the plug-in for VS2012 and VS2013 were most important to me. In addition, Sandcastle Help File Builder itself is also installed, which is an application that allows you to use the interface, rather than register everything in xml files. With the exception of the text editing toolbar (bold, italics, etc.), I did not find any differences between SHFB and the plug-in for the studio, and the studio also offers auto-complete with intelligence, so I gradually transferred the development to it.
Project setup
When everything is set, you can add the project to the solution. In the studio in the templates appeared “Documentation / Sandcastle Help File Builder Project”, select it, add “Documentation Sources” (link to the project that we are documenting), include “XML documentation file” in the project, and run the build. We go into the / bin folder ... and we 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 it 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 a chm file. Do not pay attention to appearance and warnings yet.
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, while other browsers at best open such a help with the corresponding plug-in. It’s easier to generate a Website: project properties -> Build -> turn on “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 may not work when building from studio and SHFB - build through msbuild).
As soon as you add Website, you can find the following problem: both help appear in one 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.
Output Deployment plugin
There is very little left to put the project in order.
In the Website / html directory, all files are of the form [GUID] .htm. To fix this, go to the project properties -> Help File and change the “Topic file naming method” property from “GUID” to the more readable “Member name”. Now the address in the browser line will reflect the page on which the user is located.
In those places where there is no documentation, red warning signs “Missing documentation for ...” appear in the help.
Such inscriptions are convenient for development, but completely unacceptable in the finished documentation. To remove them, go to the project properties -> Missing Tags and select which elements should not display messages if they do not have documentation. Also currently used languages are C #, VB, C ++, F #. Project Properties -> Help File -> Syntax Filters and select only those languages that are needed.
Let's create a couple of pages
First, delete the Version History folder with all the contents and the Welcome.aml page from the project. The structure of the documentation is built precisely in the file ContentLayout.content, so you have to clean this file.
In most cases, when creating a new documentation page, you will 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 for configuring static pages relative to the generated code and each other are very large, you can create a topic tree as you want.
Documentation pages link to each other using topic ID. It can be found at the top of the page in the corresponding attribute.
Example:
Problems begin when you need to link to the generated pages. In this case, Sandcastle disagrees with the syntax used in the meta tags.
M:SandcastleSample.Samples.ConstructorsSamples.#ctor(System.String,System.Int32) M:SandcastleSample.Samples.MethodsSamples.MethodWithRefParameter(System.String,System.String@) qualifyHint is set to true if you want to show the signature of the method.
Link Design List
Original
| Applicable to | The rule | Example |
|---|---|---|
| Methods and Properties with Arguments | An argument list in parentheses is required. | M: Foo.Bar.Func (System.Boolean) |
| Methods and properties without arguments | Brackets should not be used | M: Foo.Bar.Func |
| Constructors | Used by #ctor instead of name. If the constructor has parameters, then the same rule is used as for the method with parameters | M: Foo.Bar. # Ctor |
| Static Constructors | Used by #ctor instead of name | M: Foo.Bar. # Cctor |
| Finalizers | The method name is Finalize. | M: Foo.Bar.Finalize |
| Arguments | Separated by commas, with no spaces. Their name is used with the namespace. Those. instead of int , System.Int32 is used , etc. | M: Foo.Bar.Func (System.Int32, System.String, Foo.Widget) |
| out and ref parameters | Their type name ends with an @ | M: Foo.Bar.Func (System.Int32 @) |
| Parameters marked as params | No special notation | |
| Parameters that define a generic type | An apostrophe character with a generic type number is added | T: Foo.Bar`1 |
| Arrays as parameters | Array dimension can be omitted | M: Foo.Bar.Func (System.Int32 [0:, 0:]) |
| Parameters that reference types such as List <> | Using comma-delimited arguments of a generic type enclosed in curly braces | M: Foo.Bar.Func (System.Collections.Generic.List {System.String}) |
Original
The list is large, and you just have to know such things, there's nothing to be done.
Although you can turn on 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 - they are both not deprecated, and their behavior is different. For example, in vs2013, after searching, the topic opens in a new tab, which was critical on our project. It is also worth noting that Webhelp can be referenced both on 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 this class in it:
///Namespace summary ///internal class NamespaceDoc { //EMPTY }
The same thing can be done through Sandcastle. - To add a description to the topic of the generated overloaded method, use the tag:
////// Go to overload ////// /// ///To link to both overloads use 'O': ///O:SandcastleSample.Samples.MethodsSamples.MethodWithOverload/// /// public void MethodWithOverload(string param) { }'overloads' tag used in Sandcastle to put some additional inforation to "Ovetrload methods" page in the documentation. ///
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, a link to the project with examples on github .