   Library documentation tools
  I'm currently working on a library which I expect to eventually release in some form and thus I would really like to put together some documentation for the API (primarily C++, but with some C# parts). Something like the DirectX or Havok documentation (both have documentation that I consider pretty impressive though my needs are probably more like those of the DX team). However I have never done any real documentation of software projects and am unsure what tools are available for this purpose. I know Doxygen works to document the actual interface, however I would also like to document the high-level architecture, provide performance-related tips and include introductory articles. I'm not really sure whether Doxygen is capable of doing this, but I'm under the (perhaps mistaken) impression that this isn't what Doxygen was designed for and as such it will be pretty hard to write good documentation that includes formulas, graphs and heading.I'm looking for suggestions as to what tools people would recommend. I need the ability to write articles with headings and subheadings that include source code, diagrams (images) and cross-references in the hyper-text versions. I would like a system that is capable of outputting in CHM, PDF and HTML though I will settle for support for just one if necessary. I will also need to draw diagrams and flowcharts and I'm also not sure what to get for this. I tried installing Visio, but it seemed pretty hard to produce anything good-looking without spending hours moving arrows around, but perhaps this is just because I'm completely inexperienced with this type of tool. It would also be nice for some kind of mathematical typesetting support; preferably LaTeX, but something like Microsoft's equation editor is fine (though I don't see why that would be supported unless some Office tool proves adequate). I would prefer if API documentation is kept in the source files, and I don't really care about the location of the rest.I guess quite a few people here have had to write documentation for some software projects so it would be cool to hear about your experiences and suggestions.   
  For C#, I use Sandcastle, which can generate documentation in a variety of formats from the XML documentation comments in your source code.For another project I used MediaWiki and wrote an extremely hacky utility that would turn that into static HTML and a CHM, though I had a number of issues with this and would not recommend it (especially as you need diagrams etc). Having it in a Wiki had some advantages (eg easy cross-linking of articles, built-in support for categories and so on and so forth) so if you could find a similar system that doesn't have the issues MediaWiki has (I had a number of topics that needed to have # in their name, which MediaWiki doesn't support) that could be worth a look.   