Apache Forrest as a Code Documentation Solution

Question

Lately, I have been looking into Apache Forrest as a code documentation solution. From Apache's website,

"Apache Forrest™ software is a publishing framework that transforms input from various sources into a unified presentation in one or more output formats. The modular and extensible plug-in architecture of Apache Forrest is based on Apache Cocoon and the relevant industry standards that separate presentation from content. Forrest can generate static documents, or be used as a dynamic server, or be deployed by its automated facility."

I was wondering if Apache Forrest could be used as a way to organize and post documentation of some java code which is complete with JavaDoc comments. I know JavaDoc can do it itself, but I feel like Apache Forrest provides some additional customization. I found instructions on the Apache website on how to include it in Maven, but it appears to be tailored towards Maven 1.x and I use Maven 2. Is something like this possible? And if so, what is the best way to go about integrating it?

Thanks ahead of time.

Answer 1

In Documenting Projects with Apache Forrest, the author writes this about Forrest Alternatives:

If you're familiar with Maven, you may be wondering why anyone would bother with Forrest. Maven does everything Forrest does, and much more: completely automating your build, attaching JUnit and CVS reports and all sorts of additional useful information on top of the basic documentation. It even provides targets to auto-install your newly generated web site onto a remote host.

I have used Maven on a number of projects, and it's an impressive package. The learning curve is not much worse than Forrest's for basic use, and since you don't have to learn Ant if you use Maven, it's arguably even less for setting up a project from scratch. Forrest as a whole is less complex, though, and if you don't need everything Maven provides, you might want to start with Forrest and migrate to Maven later if you need it. Forrest is also better if you have an existing large-build system based on Ant: it lets you add in Maven-style web site generation incrementally instead of rewriting all your build scripts to Maven-ize the project.

In terms of pure-documentation alternatives, another solid option with a lot of open source community support is DocBook. You could write the manual for a 747 with DocBook: it's the ultimate SGML (or XML; there are two versions) dialect for technical writing. The XML variant has a nice set of stylesheets from Norman Walsh that can generate HTML, PDF, RTF (Microsoft Word) and other formats from DocBook source. I think Forrest's XML dialect covers 80 percent of the cases, with a much smaller learning curve, but for a large project that also needs to produce print documentation, DocBook merits consideration. Note that if you want to migrate from DocBook, Forrest supports rendering a subset of DocBook/XML as well, but it is not well supported. Forrest does not aim to become a full-fledged DocBook renderer any time in the future, either, according to one of the developers, so I would not rely upon it as a format for new documentation in Forrest.

So, as you're already using Maven, I really wonder why you would look at Forrest. Check out Maven Doxia if you still have some doubts about Maven's potential.

And if you want to use DocBook and if Maven's native support through Doxia is too limited, there is the Docbkx Maven Plugin (preferred over the Maven Docbook plugin).