The reception it’s received has been positive, I never expected it to have a surge of popularity because it’s not that kind of tool, so it hasn’t come as much of a surprise that people haven’t been jumping all over it. Having said that though, I have had some good feedback and already someone has contributed a patch. Additionally, there hasn’t been one question as to why I’ve created it; now this has come as a surprise, I guess I’m not the only one that feels Sandcastle is bloated and overcomplicated. Yay!

I’ve just pushed out some changes to the github repos and released an updated alpha (v0.1.0.2) on the downloads page. The biggest changes so far are the inclusion of events and fields in the parsing, which now means docu has <summary /> support for all documentable members. The rest of the changes are mainly refactorings and some battle-hardening.

I’ve got some more changes and several issues lined up, so keep an eye out.

• Anyone have any tips on generating html docs from XML comments? Used to do it years ago with NDoc ?
• Man, sandcastle is so overly complex ?
• Sandcastle examples don’t even work. This is shit. ?
• Why isn’t sandcastle just a console app that takes a list of dlls and spits out html/chm? What’s with all the batch files and XslTransforms? ?
• @AndrewNStewart Well Sandcastle requires chaining together several calls to 3+ applications before you get anything. ?
• Are these Sandcastle generated MSDN-style API docs actually useful to anyone? ?
• @pollingj It’s a dilemma. I don’t care about API docs, but people seem to want it, but I’m reluctant to generate msdn-like shit. Dilemma. ?

So as you can see, dilemma. People want API documentation (for Fluent NHibernate specifically), but I don’t want to associate myself with the awful MSDN-style documentation that’s produced by Sandcastle.

Before you get all hot under the collar, if you like Sandcastle, or you like MSDN-style documentation, leave now. Use what works for you, it doesn’t work for me so I’m not using it, but I don’t want to stop you using it.

I realise the market for this tool is probably pretty small, but it’s useful to me so it might be useful to you.

Introducing docu, the simple documentation generator for .Net!

Docu is a tool that produces an html site (or rather, a collection of html pages) from the doc-comments you include in your code. Given an assembly and the Visual Studio produced XML of the comments, docu will produce a completely static collection of pages that you can publish anywhere you like. You run it through one command-line tool, with one parameter. That’s it, nothing complicated.

docu your-assembly.dll

You can see an example of the default style that’s provided in the Fluent NHibernate API docs (the colour scheme has been modified, but everything else is default).

Docu is completely stand alone, no GAC deployed assemblies, no hard-coded paths, no nothing. This makes it trivial to use docu in your CI process for building up-to-the-second API docs for publishing or downloading.

The templates that docu uses are created with the Spark view engine which means you have all the power of C# and it’s templating language at your finger-tips. If you’re particularly picky about appearance (like I am) then you can completely rewrite the templates to your heart’s content. There’s no imposed structure or style, it’s all customisable through the templates. You can read more about customising templates on the site: customising templates.

An interesting little feature of the templating system is special names for directories and files, for example if you name a template !namespace.spark, a html page will be produced for a each namespace in your assembly using that template. This allows you to do things like create a directory for each namespace, with a page for each type in that namespace inside. Pretty powerful!

The codebase is reasonably well structured, but the code itself is a bit untidy. Luckily it’s covered by nearly 200 unit tests (so far) and i’ll be leveraging them to improve the code quality over time. You can checkout the code from the docu github repo.

It’s early days yet, there’s very little customisation of the documentation process (the part that actually finds the types and members to document), and not all comment types are supported yet; however, it’s used for Fluent NHibernate and works pretty well. It’s only Alpha right now, so you shouldn’t expect the world.

So if this kind-of thing interests you, go have a read of the docu website and let me know how it works out for you.