Velocity Site

Velocity, like some other moving open source projects, suffers from the fact that its home page is sometimes a bit outdated, or when updated to the lastest release, the docs for older versions are not readily available. The Velocity Site is an attempt to change this situation and allow Velocity Developers and User to concentrate on the things that they want to do instead of either hunting for docs or looking on where to add documentation.

How to deal with this problem?

The documentation for a project can be split up into multiple parts:

  • Global information. Information that is true for all parts of Velocity. Examples are the global project description, download sites, list of project members, links to the mailing list and issue trackers and everything that does not change from release to release.
  • Released documentation. Nothing is worse than having to use version <foo> and not finding the docs for it, because Version <foo> + 1 has been released and the site building has nuked all the older docs. Some projects have suffered from this and e.g. Struts has found a nice solution to deal with this. Released docs is frozen at the release time and then archived. It should not be changed, once a release has hit the distribution servers.
  • Current documentation. This is the bleeding edge doc right from the build process / SCM HEAD. This can be generated automatically (e.g. by a cron job) and is not really guaranteed to exist or be correct at all times.

How to apply these rules to the current Velocity site?

Currently, Velocity keeps most of its eggs in one basket. Which means, most of the docs are included with the Velocity distribution. This makes it awkward to link to the sub-projects like VelocityTools and really hard to do versioning.

Therefore, starting with Velocity 1.5, the current Velocity docs are split into multiple parts and reorganized the tree of the current velocity site.

File organization of the new Velocity Site

/------+-- index.html   Main page of the Velocity site
       +-- .htaccess    Rewrite Rules for a number of "well known"
       |                references and links published on the net
       |
       +--- site -----  Global, Velocity specific documents
       |
       +--- images ---  Global, Graphics, images etc.
       |
       +--- engine  --- Current Velocity Engine docs
       |
       +--- tools   --- Current VelocityTools docs
       |
       +--- dvsl    --- Current DVSL docs
       |
       |
       +--- releases ---+--- Release main directory. As soon as a sub-project does a
       |                |    released version, it gets moved into this directory
       |                |
       |                +----- engine ---+--- Velocity engine releases
       |                |                |
       |                |                +---- 1.3.1  --- Velocity 1.3.1 release docs
       |                |                +---- 1.4    --- Velocity 1.4 release docs
       |                |                +---- 1.5    --- Velocity 1.5 release docs
       |                |
       |                +----- tools ----+--- VelocityTools releases
       |                |                |
       |                |                +---- 1.2 -- Velocity Tools 1.2 release docs
       |                |                +---- 1.3 -- Velocity Tools 1.3 release docs
       |                |
       |                +----- dvsl -----+----- DVSL releases

The various sub trees can be published at different frequencies (and also with different tools). None of the projects may publish directly into the releases tree; moving a release there should be kept a manual task supervised by the release manager.

Menu organization of the site

When building the site in different parts, one of the problems is, that the navigation must be able to link the different parts of the site together. Using maven for building (or ant + anakia), there is a navigation.xml file which contains all the left-side menu and also top-menu links.

The top-menu links should be used to link between the main projects of the Velocity site. It should look like this:

  Home | Engine | Tools | DVSL | ...(add more sub-projects)...

This should be the same for all the sub projects.

The left-side menu links are sub project specific and should link their own docs.

SCM organization of the site

The various docs are kept in different trees on the Apache Subversion repository. The site module is located at /repos/asf/jakarta/velocity/site/trunk. Each of the sub projects keeps its docs in their own repository.

Building site parts

Site module

The Velocity site module uses Apache Maven as its build tool:

svn checkout http://svn.apache.org/repos/asf/jakarta/velocity/site/trunk site
cd site
maven site

builds the site module into the target/docs directory.

Engine module

The engine module uses Apache ant to build the documentation bundled with the distribution but uses Maven to build the site module at jakarta.apache.org

TODO

Tools module

TODO

DVSL module

TODO

  • No labels