BT

A Look Back at NDoc and Sandcastle

| by Jonathan Allen Follow 553 Followers on May 05, 2014. Estimated reading time: 3 minutes |

Since nearly the beginning C# has supported a JavaDoc-like syntax called XML Comments. The compiler extracts these into XML files, one per assembly, which can then be run through a tool that converts them into PDFs, web pages, Help files, etc. The question is, where do you get that tool? It isn’t part of Visual Studio or the .NET Framework.

For a few years the answer was NDoc. The project was going well until the release of .NET 2.0, which added generics. This was a major change to the file format and it would require a significant investment to update NDoc to support it.

The lead developer, Kevin Downs, was working on it but was forced to abandon the effort because of the combination of three factors:

  • First was the lack of community support. No developers using the tool were willing to donate time or money to the cause.
  • The second factor was a series of anonymous threats made to him and his family. Ostensibly the reason for the attacks was that NDoc 2 wasn’t being completed fast enough. To add insult to injury, whomever made the threats took the time to setup an “email bomb” that repeated the message so many times that Kevin’s email service was suspended.
  • Finally there was the announcement that Microsoft would be releasing Sandcastle, their own help file compiler. So like many people, Kevin assumed that Sandcastle would eventually become the de facto tool.

That didn’t really happen because Sandcastle on its own was simply too hard to use. In theory one should be able to simply point the tool at a set of DLLs and XML files, set a few options, and let it run. In practice most developers gave up long before they got anywhere near producing their first batch of documents. So if not for the other issues, NDoc probably would have continued to be wildly popular. But without that option, third party wrappers were created to ease the process.

Sandcastle itself was originally a closed source project being delivered via CodePlex. As many of you are aware, CodePlex was envisioned as a replacement for GotDotNet that would only host open source projects. So after a public outcry in 2008, the source code for Sandcastle was uploaded onto Codeplex under the Microsoft Public License.

Two years later, Sandcastle saw its final official release from Microsoft. That was in June 2010, but it took another two years for Microsoft actually admit that they’ve reached their breaking point and that they intended to walk away from the project.

This is where Eric Woodruff and his Sandcastle Help File Builder comes into the story. In a deal worked out with Darren Parker of Microsoft, Eric would take official ownership of Sandcastle in October of 2012 and merge Sandcastle into the his project. Due to some open legal questions, he wasn’t able to actually claim the Sandcastle site on Codeplex so a fork was created with the original pointing to his project.

As of last month both Sandcastle and Sandcastle Help File Builder are both seeing regular releases, something that Microsoft was unable to achieve during the years they governed the project. Changes in the most recent release include,

  • The Sandcastle Tools and Sandcastle Help File Builder have been merged into a single common folder structure. This was necessary to facilitate some of the other changes.
  • NOTE: The Sandcastle tools are now installed as part of the Sandcastle Help File Builder and there is no longer a separate installer for them. As such, you will need to manually remove the prior release of the Sandcastle tools. Leaving them installed will not cause any issues as the new release is located in a different folder. However, removing them will avoid any confusion in the future.
  • All plug-ins, build components, syntax generators, and custom presentation styles are now MEF components. This makes it much easier to implement project-specific components.
  • With the above changes and the implementation of a new Component Path project property, the DXROOT and SHFBCOMPONENTROOT environment variables are no longer needed. SHFBROOT is used to locate all components and the Component Path project property is used to locate project-specific build components. The application data folder can still be used to install components in a common, shared location accessible to all projects.
  • Application of the visibility options has been moved from the help file builder into MRefBuilder.
  • A new Open XML format and presentation style have been added. See the related help topic for details on its specific requirements and limitations.
  • A new preliminary VS2013 presentation style has been added.

Rate this Article

Adoption Stage
Style

Hello stranger!

You need to Register an InfoQ account or or login to post comments. But there's so much more behind being registered.

Get the most out of the InfoQ experience.

Tell us what you think

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

NDoc is not dead, it's just resting by David Keaveny

Actually, there have been signs of life around NDoc recently (I blogged this back in 2012 davidkeaveny.blogspot.com.au/2012/08/ndoc3-mode...), but stuff is definitely still happening.

Great project by Frans Bouma

SHFB is one of those open source projects which don't get enough praise from the community, while potentially everyone benefits from using them. Hats off to Woodruff for creating SHFB and creating such a solid package.

SHFB is great by Lucas Vogel

Having painstakingly built a large documentation project with SHFB in the past, I can greatly appreciate the efforts made by Eric Woodruff to integrate into Visual Studio. I agree with the other posters - hats off to Eric Woodruff for all of the work he's done!

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

Allowed html: a,b,br,blockquote,i,li,pre,u,ul,p

Email me replies to any of my messages in this thread

3 Discuss

Login to InfoQ to interact with what matters most to you.


Recover your password...

Follow

Follow your favorite topics and editors

Quick overview of most important highlights in the industry and on the site.

Like

More signal, less noise

Build your own feed by choosing topics you want to read about and editors you want to hear from.

Notifications

Stay up-to-date

Set up your notifications and don't miss out on content that matters to you

BT