The Velocity project used a simple HTML based format called XDOC for its documentation for a very long time. However, XDOC is not really popular outside the Apache world[1], it renders somehow into HTML but no other formats (unless you consider a set of alpha and beta-level plugins for maven-1 and maven-2) and tool support for this format is not really there.
When an XML based format for documentation is considered, DocBook seems to be a natural choice. So we decided to take a stab at rendering the existing Velocity Docs that are end-user specific (Users Guide, Developers Guide, Reference and the likes) through DocBook.
What we wanted to have, was a framework, that...
...renders multiple documents into multiple formats with an uniform look without having to copy a large number of stylesheets, images and other supporting files around.
...separates the render framework and the actual documentation to render. It should be sufficient to install the framework only once and then reference it.
...uses the standard DocBook XML and XSL zip files available for download. Many of the open source DocBook frameworks use heavily hacked versions and we want to be able to keep up with releases without having to patch the released files every time.
...uses current versions of the DocBook reference files, the libraries and supporting tools.
...render all formats without connecting to the Internet.
Using the Apache XML resolver, it should be possible to use the
framework completely standalone. See
http://xml.apache.org/commons/components/resolver/resolver-article.html
for an explanation.
...has some documentation so you understand what happens when a format gets rendered and how.
...that can be customized easily (if you consider customizing complex XSL style sheets 'easy').
...that is platform independent and uses 100% pure Java. No external programs should be needed or called.
...that is driven by Apache ant and could be easily embedded into larger builds.