+972 52-548-6969
Generating API Documentation
I want to generate API documentation for Raven DB. I decided to take the plunge and generate XML documentation, and to ensure that I’ll be good, I marked the “Warnings as Errors” checkbox.
864 compiler errors later (I spiked this with a single project), I had a compiling build and a pretty good initial XML documentation. The next step was to decide how to go from simple XML documentation to a human readable documentation.
Almost by default, I checked Sandcastle, unfortunately, I couldn’t figure out how to get this working at all. Sandcastle Help File Builder seems the way to go, though. And using that GUI, I had a working project in a minute or two. There are a lot of options, but I just went with the default ones and hit build. While it was building, I had the following thoughts:
- I didn’t like that it required installation.
- I didn’t know whatever you can easily put it in a build script.
The problem was that generating the documentation (a CHM) took over three and a half minutes.
I then tried Docu. It didn’t work, saying that my assembly was in the wrong format. Took me a while to figure out exactly why, but eventually it dawned on me that Raven is a 4.0 project, while Docu is a 3.5. I tried recompiling it for 4.0, but it gave me an error there as well, something about duplicate mscorlib, at which point I decided to drop it. That was also because I didn’t really like the format of the API it generated, but that is beside the point.
I then tried doxygen, which I have used in the past. The problem here is the sheer number of options you have. Luckily, it is very simple to setup using Doxywizard, and the generated documentation looks pretty nice as well. It also take a while, but significantly faster than Sandcastle.
Next on the list was MonoDoc, where I could generate the initial set of XML files, but was unable to run the actual mono doc browser. I am not quite sure why that happened, but it kept complaining that the result was too large.
I also checked VSDocman, which is pretty nice.
All in all, I think that I’ll go with doxygen, it being the simplest by far and generating (OOTB) HTML format that I really like.
Comments
" it gave me an error there as well, something about duplicate mscorlib,"
Could be you need to bump up the tools version in the csproj.
2.0 tools don't know how to build 4.0 projects so they always pull in the old mscorlib.
"I didn’t know whatever you can easily put it in a build script."
The saved file output from the Sandcastle Help File Builder is an MSBuild-based project file, so it should integrate well with a build script.
Hi Ayende
With Sandcastle, you can speed up the build substantially doing the following:
Click on the "ComponentConfigurations" properties button, and add "Cached Framework Comments Index Data", "Cached MSDN URL References", and "Cached Reflection Index Data".
HTH,
Matt
What?! No Rhino.Doc?
(Sorry, I know the joke is getting old.)
We settled on Doxygen for Caliburn (though I believe that was two years ago).
You didn't try Document! X?
It's commercial, true, but gives the least # of friction (although VSDocMan also looks nice) as in: you don't have to spent extra time when writing code.
Another vote for Document X - the other nice thing is that you can put topics other than straight API stuff
This is something that's puzzled me for a while - Why .NET does not have a standard document generator. Ruby has RDoc. I too tried Sandcastle a couple of years ago but gave up as well. It's not a product but a set of (very raw) tools - it's just too much hard work to use. Doxygen on the other hand is good, but is not .NET specific, and does not seem to cope with all edge cases in .NET. Maybe the thought of building Rhino.Doc isn't such a bad idea ???
Matt,
Thanks, that took over 2 minutes from the help build time
About a year ago I was using DocProject, http://docproject.codeplex.com/. It installs VS template which you can use to create the project and integrates into msbuld quite nicely.
Comment preview