Tools for generating HTML documentation

Question

I've been writing documentation files in raw HTML for a small open source project in Java. Now I'm wondering if there are any good tools to automatically generate the HTML docs from some source files during the build process, with the main advantages being substitution of ${variables} and a consistent layout across all pages.

An important aspect is internationalization: It should be easy for translators to edit the source files in order to generate localized documentation, and the tool should properly deal with different encodings.

EDIT: I'm not talking about generating documentation for program source code, such as Javadoc, but documentation for the non-programmer end user. In other words, "the manual".

Answer 1

have you checked out Doxygen? It natively supports Java (as well as C/C++/Python) and will generate HTML documentation from your source. Of course, you have to put in the time to (1) configure the tool, and (2) outfit your code with Doxygen comments. I've only used this with C so I can't speak to the Java documentation quality - but I was impressed with the C features.

One of the biggest problems is making sure that all of your contributors understand the need for auto-generated documentation and are willing to spend an extra 10% of their time updating/creating the appropriate comments. If it's done right it's really slick.

Answer 2

I read a lot of people using Doxygen.

http://www.stack.nl/~dimitri/doxygen/