Class Documentation Suggestions

Question

We are a Microsoft shop, concentrated on using C#. We have several projects, including websites, Windows services, and class libraries, that incorporate XML comments.

I'm looking to generate MSDN-style HTML documentation for each project and deploy it to a centralized location that all of the developers can easily access. I also want to automate these steps so they can be run at regular intervals so I, and the other developers, don't need to worry about remembering to generate and deploy new documentation whenever a change is made. I've looked at Sandcastle and Doxygen and both look to be good options for generating the documentation that I want, but I need advice on a good way to automate the generation of it, like in a nightly job or something.

Anyone out there doing something like this? I'm not sold on the end result being HTML; especially if there is a better idea.

EDIT:

I appreciate all of the good ideas. There are a couple of routes now that I can investigate, but I won't know which will work best until I get my hands dirty. The Sandcastle Help File Builder seems to offer me the best options for what I'm looking to do, so I'll give the nod to that suggestion. However, if I had more time to work on the XSLT and CSS solution to get the XML data looking just right, I'd pursue that suggestion first.

Thanks again everyone!

Answer 1

Take a look at Sandcastle Help File Builder. This uses standalone projects, so you can build them as often as you like (for example nightly, or as part of your continuous integration system every time a change is checked in).

Answer 2

You don't need any third-party tools to generate nice documentation: C# compiler can output the documentation from XML-comments in XML and all you need is to design a nice CSS to show it in browser. If you are not satisfied, you can also generate your own XSLT-transoformation before applying CSS, as described here (look for an example of CSS in comments!).

Alternatively you can take this XML documentation and improve it using something like NDoc. Here is a nice article about how to do it, unfortunately somewhat outdated.

You can manually build only the documentation of your project into a single XML file by running the compiler with /doc:documentationfilename.xml parameter.

You can also indicate in Visual Studio (Project Properties -> Documentation) to add this option to every build of your project, so that XML file will be generated every time you build your project. You can then hook post-build events to copy the XML file to your repository.

You can also set up your MS Build on your Team Foundation Server to build your documentation and copy it to the repository in a similar way (/p:DocumentationFile=fileName.xml);

Answer 3

I do that with our projects. Basically we use doxywizard to set up the configuration Doxyfile, which will set the specifications for the generated html. Then, in a build server step I invoke "doxygen doxyfile".

Our Doxyfile is configured to generate the doxygen files in an area visible from our webserver. So, each commit to trunk causes documentation to be rebuilt automatically.