I've never used a documentation system before, typically using commenting by hand but I think it would be nice to do so for a new project. What do you guys/gals advise? I've heard of Sandcastle but not sure if that's the best out.
(This is for an open-source project so it needs to be free unfortunately.)
Sandcastle is great. It's replaces NDoc nicely and is fairly easy to setup.
I've written up a previous entry with some links you may find beneficial to look at: http://stackoverflow.com/questions/319632/docproject-vs-sandcastle-help-file-builder-gui#398060
Sandcastle will create documentation in either HTML, HTML Help 1.x (.CHM) file or HTML Help 2.x (.HxS) file format from your XML comments in your code in the style of MSDN that is fully searchable with table of contents, etc..
In theory there is very little work extra work you would need to do in order to get very fully documentation. It can also be styled using stylesheets to look completely different.
There is an application (free) on CodePlex called Sandcastle Help File Builder (SHFB) that can help you construct/configure the documentation using Sandcastle.
I personally have used this and in my opinion it was easy to setup using SHFB to configure it. You can also schedule it to re-build as part of an automated build process if you want to use the command-line.
First off, I don't see how there could be anything unfortunate about working on an opensource project ;) But to an attempt at answering your question would be doxygen.
I've been using doxygen in a C# project a few years ago and it functionality and output options are simply unbeatable. It's fairly easy to set up, and it has built in support for C#. Besides the usual HTML, doxygen can produce LaTeX, RTF, PostScript, hyperlinked PDF, compressed HTML, and Unix man pages. It can read and produce lists of all flavours of TODO, \todo, ToDO, FIXME, BROKEN or any other 'annotation' you or coders before you have made in the code. It can inline images and link internally in the code base on namespaces, packages or whatever your language calls modules nowadays.
Dimitri (the author of doxygen) is very responsive and helpful and the community around doxygen is very active as well.
To get started, simply open a prompt and type:
Doxygen -g
and voila: you have yourself a fully documented configuration file!
There's also a short tutorial for Windows users here.
The original NDoc project (mentioned by others) is dead, but there is a new project called NDoc3.
NDoc3 supports .NET 2.0 - 3.5. It is currently available as a beta version and worked great for me. I'm not sure if the project is still active - the last beta was release in april 2009.
I found Starcastle rather difficult to set up, undocumented and even somewhat buggy. Also, I didn't fancy that the vs2005 style generates a separate page for a type and its members. Starcastle is very good for large, public documentation like MSDN, but for simple internal documentation, I recommend mdoc from the Mono project.
To generate documentation from a XML comment file and a .NET assembly, run:
mdoc update -i comments.xml assembly.dll -o mono-xml-files
mdoc export-html mdoc-xml-files -o mdoc-html-output
The above converts the comments into mdoc's own XML format and again converts it to HTML.