I have been working on a diverse set of projects this year, primarily based around .Net, and the need for documentation consistently arises. Some projects require user manuals, others API specifications, and some would simply benefit from a list of endpoints or settings delivered in a format accessible to integrators and testers. With limited research, I found SHFB (Sandcastle Help File Builder) and many other competing products in this space. This guide is primarily focused on helping you hit the ground running with Sandcastle Help File Builder and your .Net projects in Visual Studio 2015, and is in no way a definitive guide. I will update and extend this post as time permits.
As previously mentioned, there are a plethora of competing products aimed at extracting beautiful and usable documentation from your .Net solutions. If you decide by the end of this article that SHFB isn’t for you, you may wish to check out some of the following alternatives I initially considered.
Doxygen was one of the first free products I encountered, and it looked to be well established, with a primary focus on C++. It boasts a number of large projects using it from KDE to FLAC, and is seemingly very community driven. Although the project does support .Net (and C# specifically) I was concerned that I would need to put too much effort into using an maintaining it alongside my target solutions, and all the example documentation I viewed I found visually repulsive – although I am sure this wouldn’t require much effort to correct. I may revisit this for future C/C++ projects.
NDoc seemed like a capable tool intended for use with .Net projects. Although free, it shows significant signs of age, and I am skeptical of its capabilities in contrast to the competition. To use it you set up an additional build step in your project/solution, which will take the XML documentation output from your target, and work through its own build process on this file. This seems like a fairly standard approach, but I have higher expectations.
Docu was probably my favourite of all the documentation generator/formatters that I inspected. Free, like all mentioned in this article, Docu is primarily concerned with looking great, and simplicity. James (the project author) seems to have done an excellent job, and put a lot of effort making something awesome. My only turn-aways from this, was that its IDE and build integration is minimal – although this isn’t *really* a problem, and its output capability is limited to webpage output at present. I would like to produce well formatted PDFs longer term – although I may investigate bridging the development gap in doing so with this project in future. What I particularly like about this project is how sincere and clear James is in communicating the projects intended audience and capabilities. No bull-shit, and straight to the point.
Sandcastle Help File Builder
Sandcastle is my final choice (as is now pretty obvious) with which to proceed in learning about and integrating with my projects. The Visual Studio integration makes it easy to keep track of, customise, and further extend documentation with your solution, custom project types enable you to enhance your Sandcastle project with custom components, and the available output types are diverse, from webpages to docx and chm. This all comes at the expense of a clumsy and unrefined experience, however the learning curve is seemingly less than I initially believed, and it is overall a nice product to use. My only complaint with substance from using this product is how slow it is to build.
The installation of SHFB is reasonably straight forward, however there are a couple of sneaky and less-impressive aspects to watch out for. Firstly, the installation process is irritating. It isn’t hard, and it does work, but the delivery is non-standard, and bothersome. Secondly, a restart is required to avoid nondescript errors when beginning projects and building content, which in this day and age I feel is inexcusable considering the subject is a meager development accessory. It is free though, and pretty impressive otherwise – so let’s be nice :).
- Head to the GitHub site and download the latest version. https://github.com/EWSoftware/SHFB/releases
- Extract the ZIP archive.
- Run SandcastleInstaller.exe and click through the installer.
Note that on each page, there may be an install button in the primary content area for each component; be sure to be on the lookout. It is easy to get click-happy and miss them. Also note that the restart after completion is necessary, presumably because of how the installer relies on molesting environment variables.
Preparing your project is pretty easy. You simply need to add comments in the .Net documentation style, and enable XML documentation output.
Firstly, enable documentation output.
- Open your project properties.
- Select the ‘Build’ tab.
- Under the ‘Output’ heading, select ‘XML documentation file: …’
- Save properties and rebuild.
Documenting your code is easy! Simply enter ‘///’ on the line above any aspect you would like to capture in your documentation and fill in the body of the auto-generated comment block.
If you use ReSharper, you may wish to update your preferences to automatically copy XMLdoc comments when you implement an interface or extend something. This is a great time saver, and worth integrating into your workflow.
- Open ReSharper’s options in your desired context.
- Expand the ‘Code Editing’ sub-tree.
- Select the ‘Member Generation’ node.
- Select ‘Copy XML documentation from overridden members’ option.
When you go to add a new project to your solution for sandcastle, you will likely encounter a confusing division of options. If you were to look under ‘Documentation’ projects in the ‘Visual C#’ category, you would stumble upon the options below.
Instead, add a new project, and explore the parent ‘Documentation’ category to see a singular Sandcastle option as below. Create a new ‘Sandcastle Help File Builder Project’, and this step is complete.
If you are faced with an error whilst attempting to add this project (Something about ‘Documentation1’?), it is most likely due to not restarting your computer after installing Sandcastle.
Configuring Your Sandcastle
With your solution boasting both a documentation project, and a documentable project, you are ready to progress. Next, add a documentation source to your Sandcastle project.
- Expand your Sandcastle project in the solution explorer.
- Right-click the ‘Documentation Sources’ node.
- Select ‘Add Documentation Source’
- Browse and select the *.*proj file applicable.
- Press Open.
- Build your project.
Once this is complete, it is necessary to manually add documentation for Namespaces if desired, or disable namespace documentation. To do the former, manually add namespace documentation:
- Open the project properties (for the documentation project).
- Navigate to the ‘Summaries’ tab.
- Click the ‘Edit Namespace Summaries’ button.
- Select the namespace for which a description is to be added, and type it in the bow below.
- Once complete click close.
- Save the project properties.
Once the Namespace summaries dialogue is present, it is possible to disable summary text for a namespace by deselecting it.
On the ‘Build’ tab of the documentation project’s properties, it is possible to enable more types of output. OpenXML and Markdown don’t appear to be supported out of the box, and will likely yield a build error.
he ‘ContentLayout’ file makes it possible to change page properties and manage static content. It would be advisable at this point to attempt to build your project and check out the output. This can be found in the ‘Help’ subdirectory of the project folder. Note that it may take a while to complete a build, despite Visual Studio prematurely claiming success.
The CHM output (above) despite the ugliness of its host, appears to be marginally more usable than the html output below. My very limited research suggests the necessity of server side components to support search functionality. I assumed it was handled client-side, but haven’t investigated further.
Sandcastle, although not perfect, makes it easy to create attractive and complete documentation from your source code comments, and consequently eases the burden of managing documentation. API documentation can now be minimally managed by a team member with minimal coding experience, and access the project, and easily incorporated into build processes for inclusion with releases.
I would like to explore docx/pdf output in the future, and rectifying or removing the search from the HTML output. I also observed that the side menu in the HTML output would hide components as I navigated into my tree of namespaces.
My example project on BitBucket: