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:

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.

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

VelocitySite (last edited 2009-09-20 22:06:02 by localhost)