In this article, the author gives us an introduction to Apache Forrest, a great application that helps to document any project. It is compared to other approaches such as Maven. Apache Forrest is built on top of Apache Cocoon. It can be used as a servlet for your documentation needs.

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.

Read Documenting Projects with Apache Forrest

Both HiveMind and Tapestry use Forrest to render their home pages.

Tapestry started with hand-tooled (and ugly!) HTML and migrated to Forrest last year. A good bit of the documentation is still in DocBook format however.

HiveMind started with Maven and, after a lot of frustration, converted over to Forrest. The results are quiet nice I think. I did have a few problems getting tabs working (consult the forrest-user mailing list to see the problems and the resolution).

I quite like the use of site: urls, as an abstraction away from hard coded URLs. I.e., <link href="site:faq"> rather than, perhaps, <link href="../faq.html">. I actually extended that further, defining an XML entity to &faq; that expands to <link href="site:faq">FAQ</link>. This keeps the organization of the HiveMind web site under control. Maven can do the same thing, in theory, but in practice it doesn't work (the Maven guys point the finger at Jelly and promise it will be removed ... but not in the 1.0 release!).

I use Forrest for a project web site I created in January. Overall, I'm generally pleased, and it's pretty straight-forward to do easy stuff with it.

However, I'm a tinkerer, so needed my own tweaked skin, and this ended up being more work that I wished for. XLST, CSS, XML config file tweaking. Not rocket science, but I guess I was hoping for something a little less ... cut&paste ... or something.

My site.xml file has become rather ugly over the months, and I wish there was a more introspective way of dealing with this. Namely, iterating over subfolders to get pages/titles/etc. Likewise, management of my external resources (a bunch, scattered over my directories) has become a bear.

And it's not the quickest thing on the planet.

And the skin I ripped and tweaked didn't have the auto-PDF bits enabled correctly, so I can't auto-generate PDF. Which ended up not being a real problem for me, but was a bit of a let down.

I have to admit I didn't do much more than read the docs available, and the existing skin/config files, and could probably automate a bit more of my site, but at this point, it's not really worth the hassle.

Still, overall, I'd recommend it to folks who aren't so particular and itching to tweak it. I thought I would be a little too constrained by the limited 'doc' XML format, in the end, I wasn't, even with the spartan table facilities. I've grown to love the recursive <section> elements, as a way to handle both headers and contained elements.

Personally, I'll probably do something with Anakia next. Will require much more tweaking, for sure, but ... that's ok with me.

Auto-generating site.xml would be very nice. It would be nice if the .xml files had meta data that could be used to build site.xml.

HiveMind creates a forrest-composite directory and has the project and the sub-modules copy the xml files into place. It also generates some of the content on the fly, and uses XML external entities to get access to it. It works in the end, but I do pine for something that didn't require copying so much ... plus, there's the fact that Forrest recopies everything into it's directory structure before actually running Cocoon (has something to do with how skins are implemented, and apparently will go away in the next major release).