Introducing Docu - Simple doc gen for .Net

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.

Lets look at a recent Twitter conversation of mine:

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.