the Apache Velocity Site¶

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, then refer to the STATUS file. You'll of course also need a local checkout of the site sources (the sources for the cms are in /cms/, but the process needs the whole site).

While Velocity isn't yet hosted on the CMS, you'll have to generate the site in velocity/site/production, then check added/modified/deleted files with svn status, and commit the result.

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/

Notes:

• the markdown tables extension, in the python-markdown package (python 2.7), seems broken at version 2.6.9 ; I had to revert the markdown package to 2.6.7.
• the python pygments lexer (used by markdown/codehilite for code syntax highlighting) knows about the Velocity syntax, but not about silent references like $!foo or $!{bar}. I patched it and sent the patch upstream.

Additional Notes¶

Javadocs¶

For the time being, here are the steps to build the javadocs (listed for the engine, adapt for the tools):

1. issue an mvn javadoc:aggregate -pl !velocity-custom-parser-example command at the root of the source tree (the -pl option is here to ignore a specific module from the docs)
2. copy the content of the target/site/apidocs directory inside of the apidocs directory of the apropriate module inside the site sources
3. commit this result (which will produce a first big fat commit email...)
4. generate the site then commit the production result (second horrible commit email...)

Table of Content¶

Per-page table of contents can be displayed with the following placeholder:

[TOC]

Tables¶

Tables are supported. See the documentation of the python-markdown extension.

Syntax highlighting¶

The markdown module used by the CMS allows one to specify which language lexer to use for syntax coloring of blocks of code, using the following syntax:

:::velocity
#set( $foo = 'bar' )
...

which produces:

#set( $foo = 'bar' )
 ...

There are many lexers available, among which :::java, :::html, :::xml, :::properties, :::velocity, :::html+velocity, :::xml+velocity, etc.

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...