I am currently looking for a solution to generate the documentation for some of my projects. My requirements are quite simple:
- documentation should be written in an easy format(xml, wiki-style)
- the generation step to be automatic and in simple way configurable (to allow through simple configuration a degree of customization for the generated html)
- the generated documentation must be html
I would have one more, but this represents in fact a plus: plugable in Ant.
Till this moment I have tried to use DocBook (which corresponds to all my requirements, plus Ant integration through style task). But I’ve found it hard to configure and moreover too many tags to use in order to have it looking as I wish. A second choice I am analysing now is Maven xdoc. I have passed over my unpleasant feeling about Maven (Hani you are not alone [smile/]) and start trying this. While it seems pretty configurable and the document format seems very neat, what I find difficult is to configure Maven to run my goal (yep, I can call this a goal).
I have already received a suggestion from Andreas Mecky (author of JConfig): to use a Wiki-like tool which have export to static HTML feature. Unfortunately I do not have such a tool for the moment. I was talking with Channing Walton (author of Eclipse Wiki Editor Plugin) if such a feature is on his list, and surprinsingly I have found out that I am not the first one asking about the Export to HTML feature. I am looking forward to this.
Concluding, for the moment I do not have a really nice solution for the generation of project documentation. I will keep looking and I would much appreciate if anyone of you have some suggestions/solutions for me. I hope my requirements are not too high. Our users/customers are always expecting great documentation from us. Give me the tool(s) to provide it!
mindstorms 
I use JSPWiki and export pages to HTML using Hula. Then I use an Ant’s “get” task to download all my project’s documentation.
http://raibledesigns.com/page/rd?anchor=export_jspwiki_pages_to_html
Codehaus use Atlassian’s (free to open-source) Confluence tool (wiki/blog) and have scripts that publish pages from it.
Involves a fair amount of setup to get it all going I suspect. I think the scripts are called Confluenza, but unsure.
Hen
Check out the apache forrest project
http://forrest.apache.org/
Apache Forrest is an XML standards-oriented documentation framework based upon Apache Cocoon, providing XSLT stylesheets and schemas, images and other resources. Forrest uses these to render the source content into a website via command-line, robot, or dynamic application.