the Apache Velocity Site¶

WARNING! This document might be out of date! For the latest information on how to build the Apache Velocity Site, please check out the actual README file which contains the latest information. This document has been created from the README and is not updated as often.

Introduction¶

The Apache Velocity Site is what you get when you visit our homepage. It is the envelope site for all Apache Velocity sub projects.

In short: This svn repository is only interesting for you if you

• want to re-create the Apache Velocity site on your local computer or intranet.
• are an Apache Velocity committer and want to update the site.

Editing the Site¶

Apache Velocity uses the Apache Content Management System to manage its site.

For the time being, the site is not yet hosted by the CMS (which is not yet accepting new sites before undergoing a machine transition), so the site still has to be build locally. Please refer to the next section. The rest of this section is not yet applicable.

To just edit one page, all you need is the bookmarklet found here

If you're a commiter, you'll be able to push your edits by yourself on the production site. Otherwise, the CMS will let you generate a diff file that you can send to the devs.

Commiters can also commit changes to the site under svn and trigger a publication in production from the CMS.

Building the Site¶

To build the site locally, you'll need a local checkout of the Apache CMS (check the STATUS file) and of course a local checkout of Velocity's site sources.

Typically, you'll have to:

1. define the environment variable MARKDOWN_SOCKET to something like /tmp/markdown
2. launch the CMS markdown daemon apache-cms/build/markdownd.py
3. run apache-cms/build/build_site.pl --source-base velocity/site/cms/trunk --target-base velocity/site/target (adapt the paths)
4. copy the generated files from site/target/content to site/production (including the hidden file site/target/.htaccess)
5. check the result then commit

Here's a bash script that you can reuse:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

#!/bin/bash

export MARKDOWN_SOCKET=/tmp/markdown
CMS=~/projects/velocity/apache_cms
VELOCITY=~/projects/velocity

if [[ `pidof markdownd.py` == "" ]]; then
   $CMS/build/markdownd.py
fi

find $VELOCITY/site/cms/trunk/ -name "*~" | xargs rm -v
rm -rf $VELOCITY/site/target

$CMS/build/build_site.pl --source-base $VELOCITY/site/cms/trunk --target-base $VELOCITY/site/target
cp -r $VELOCITY/site/target/content/* $VELOCITY/site/production/
cp $VELOCITY/site/target/content/.htaccess $VELOCITY/site/production/

svn status $VELOCITY/site/production/

Additional Notes¶

Breadcrumbs¶

Breadcrumbs use the full pathname of the file (one path per level). So choose filenames and structure apropriately, as directory names will be used to label each step.

Left Navigation¶

The deepest left.nav (markdown format) will be used (starting from the current page markdown script directory and going up the hierarchy).

Post-Processing¶

To be able to handle some specific dynamic parts of the site that depends upon other resources than their markdown file (aka news, contributors, changes...), a post-processing mechanism has been setup:

1. define a perl subroutine in lib/view.pm called "my_specific_section" (for instance) that returns a string
2. in the markdown file, use a {{my_specific_section}} tag wherever needed
3. in path.pm, make sure that "postprocessing => 1" is included in the parameters relative to this markdown file

The perl subroutine will be called after the markdown has been processed into html. The process is recursive: the result of a post-processing tag can contains other tags.

TODO¶

Integration of several Maven reports: dependency-convergence - subversion changelog - dev-activity - file-activity...