Sandcastle Help File Builder and VS2015

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.

Choices

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

http://www.doxygen.org/

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

http://ndoc.sourceforge.net/

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

http://docu.jagregory.com/

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

https://github.com/EWSoftware/SHFB

Sandcastle Navigated Example

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.

Getting Installed

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 :).

  1. Head to the GitHub site and download the latest version. https://github.com/EWSoftware/SHFB/releases
  2. Extract the ZIP archive.
  3. Run SandcastleInstaller.exe and click through the installer.
  4. Restart

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.

Project Preparation

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.

  1. Open your project properties.
  2. Select the ‘Build’ tab.
  3. Under the ‘Output’ heading, select ‘XML documentation file: …’
  4. Save properties and rebuild.

Target Project Properties

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.

Example Code Comment for XML Doc

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.

  1. Open ReSharper’s options in your desired context.
  2. Expand the ‘Code Editing’ sub-tree.
  3. Select the ‘Member Generation’ node.
  4. Select ‘Copy XML documentation from overridden members’ option.
  5. Save.

Resharper Options

Sandcastle

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.

Sandcastle CS Projects

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.

Documentation Projects

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.

  1. Expand your Sandcastle project in the solution explorer.
  2. Right-click the ‘Documentation Sources’ node.
  3. Select ‘Add Documentation Source’
  4. Browse and select the *.*proj file applicable.
  5. Press Open.
  6. 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:

  1. Open the project properties (for the documentation project).
  2. Navigate to the ‘Summaries’ tab.
  3. Click the ‘Edit Namespace Summaries’ button.
  4. Select the namespace for which a description is to be added, and type it in the bow below.
  5. Once complete click close.
  6. Save the project properties.

Sandcastle Namespace Summaries

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.

Sandcastle Build Options

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.

Sandcastle Example CHM File

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 HTML example

Conclusion

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.

Sandcastle Navigated Example

My example project on BitBucket:

https://bitbucket.org/gpriaulx/blog-topic-tutorial-htgrsandcastle

Adaptive Code via C#

Gary McLean Hall’s book ‘Adaptive Code via C#’ has been an invaluable reading experience. It has allowed me to transfer my shallow understanding of SOLID concepts that were filled with doubts and questions, to a comprehensive tool I can use on a daily basis to ensure my work is adaptable, and a pleasure to expand.

adaptive-code-via-c-sharp-02

So what is SOLID anyway?

SOLID represents 5 principles that support writing code which can transform with ease to changing requirements, is extremely testable, and ensures teams can comprehend large repositories with ease.

S – Single Responsibility. SRP is pivotal in supporting ‘O’ and ‘L’. It mandates that every unit has one responsibility. I had difficulty in the past defining what this responsibility should be, but Hall’s examples and explanations tore away all the irrational perceived shortcomings that I had attached to this, and left a clear understanding of ‘how to cut the cake’. The worst part about this chapter (Chapter 5), was that it left me wanting to write code immediately, but at the same time hesitant because I hadn’t experienced the glory of the remaining ‘OLID’.

O – Open/Close principle. No matter how much I read about this, I felt I understood it, but somehow completely missed the point. It states simply that the code you write should be open to extension but closed to modification. This is further clarified in ‘L’. It’s almost like a contract; ‘always do this… never do that…’, to ensure dependency graphs aren’t broken in implementation.

L – The Liskov Substitution Principle. This was always a black duck for me, in that I never really bothered to invest the time in understanding it. It extends the foundation ‘O’ builds and explains how code may be extended, and how to compromise.

I – Interface Segregation. Interfaces are what make SOLID possible. No interfaces, no SOLID. This is a no-brainer with ‘SOL’ and ‘D’ in mind, but Hall uses this chapter constructively to further explain how these principles work together.

D – Dependency Injection. I had a warped understanding of Dependency Injection, poisoned by the many pointless implementations of Inversion of Control I had seen in my working life. Adaptive Code via C# set the record straight on this for me; it explains why dependency injection is one of THE most important aspects of modern OO development, and how it supports SOLID as a whole.

My favourite part of reading this book was its layout. It is separated in to 3 sections. The first covers the justification for SOLID, what modern software engineering encompasses, an overview of Unit Testing, and some simple design patterns. The second is strictly SOLID, and the third is a role play of an Agile team working through a project, and negotiating change as it arises. All 3 sections are a rewarding read, with lots to be gained in the subtle references alone.

An accessory to SOLID that I have consistently struggled with prior to reading was Unit Testing. I understood the point, and how to write a test, and implement it, but I had never seen any useful examples of real unit tests that provide real value. The examples expressed in Chapter 4, whilst shallow, set me on a path to bridge this gap, and I now can confidently and comfortably use unit testing to support my projects without hindrance.

Overall, the code examples are very simple to follow, and concise. If anything, they are too simple. The experienced programmer would likely look at them and understand the concept that is being displayed and discussed, however a lesser experienced programmer would probably identify all the techniques used, but may miss the underlying point of the particular arrangement in context.

The text generally read very well. I have had text books that have taken me hours to pass less than 5 pages. Adaptive code was very easy to get though more than 30 pages per hour however, and an IDE is not necessary. It was really relaxing to read. I would recommend it to all Java and C# developers interested architecture, and writing better applications, and the first section to non-programmers in the Software Engineering industry with an interest in quality software.

ANPR/LPR Heat Map Analysis

I created a simple utility today to assist in evaluating the alignment and environment factors of an LPR camera installation,  based on metadata produced by an LPR engine.

LPR is almost an art – having a great quality image, a well-tuned engine, and ideal ambient conditions are not enough to ensure best performance. Quite often, the engineering aspects of an installation far outweigh any ability to improve accuracy in software. Consequently, domain knowledge and experience is imperative to ensure that an LPR installation performs to the best of its capability.

By analysing the positions of a set of number plates in a camera’s field of view (FOV) with respect to confidence, correctness, and status; a lot of information regarding the camera can be deduced which in turn helps improve system performance.

Projects-Heatmap-01

Manual sampling can go a long way with the right knowledge. From the image above, it is easy to see that alignment could likely be changed in such a way that the region in which number plates present themselves is more central to the camera. This of course would help improve capture rate – one of the standard benchmark vectors of an LPR system. Doing so would likely just introduce reads prematurely, and adversely impact performance. This would then require the engine to be retuned; but the nature of how to do so can be difficult to deduce. Hence analysis can be quite complex, and problems can quickly compound and become overwhelming.

Projects-Heatmap-02

When viewed on a heat map, this requirement for alignment becomes immediately obvious. It is no longer necessary to be consciously aware of what’s going on during an accuracy audit – the necessary actions can be deduced entirely from the data in this image and the statistics that accompany it.

Projects-Heatmap-03

Different scenarios present different problems of course – like in this image it can be observed that the system read accuracy is quite good, as implied by lots of green. However, the congregation of these reads could be centralised in the FOV, permitting plates which might be uncaptured presently to be captured as they pass through a currently excluded region.

Projects-Heatmap-06

False positives can impact different systems in different ways. In some systems that rely on inferred transactions, they can cause havoc; creating invalid transactions which may have devastating roll-on effects. In other systems, they might go completely unnoticed. Regardless, as with any real-time transactional system that deals with images, space is a premium, and wasting it on useless data is an expensive penalty. A ‘next-step’ from considering a map with similar formations to this could be to filter reads that fall in the yellow regions (false positives), and possibly realign the device to re-centralise the hot spot. It may even justify considering a read-confidence filter to stop them existing in the first place.

Projects-Heatmap-04

An even distribution of misreads might indicate that the engine is not tuned or simply not capable enough to read the plate formats being presented. That is not the case in this scenario however, as the congregation of red regions central to the image, of a small size, tells us that the plate is too small to optimally read, and that a size filter will likely improve the system’s performance dramatically. Furthermore, a region filter could be applied to eliminate almost all the false positives with confidence, and minimal side effects.

Overall, I am really happy with how this process makes it easier to form educated decisions, with lowered risk. I will likely develop this tool further, to interface with more systems and engines to make it easier to quickly assess the quality of an installation with respect to the engineering decisions made, and of course, rectify any issues that may be present.