The Jakarta-Site2 module is where we store the code for building our static HTML website. We use XML files as our input and transform them into static HTML files (which is what you are reading now). The reason why we use static HTML is because the apache.org server gets a huge number of "hits" each day. Having a dynamic site would increase the load on the server to an even more unacceptable level because apache.org is a limited resource shared by hundreds of people. Using XML as our input allows us to change the look and feel of the entire site in a matter of seconds.

Each Jakarta project has the choice of how they generate their website and documentation. The "encouraged" way is to use the Jakarta-Site2 module as the basis for generating the documentation. The provides a consistent look and feel for all of the Jakarta sites pages. As you browse various projects, you may notice slight variations in the look of the site. This is because other projects have chosen to use different technologies for transforming their XML files and have not kept up with the general look and feel of the main Jakarta Site. This is perfectly ok with us as we allow our developers the freedom to innovate.

The jakarta-site2 module uses Anakia to do the XML->HTML transformations. Therefore, it is highly recommended that you read the Anakia documentation in order to get an overview of what you are dealing with (it really is quite simple as you will soon discover).

If you would like to use the jakarta-site2 module as a dependency for your project, here are the instructions for how to do that. The benefit of using it as a dependency is that you will be able to easily adopt the look and feel of the entire Jakarta website while being able to continue to have control over your own project's documentation navigation. It is the recommended, but optional way to develop documentation for projects hosted under the main Jakarta Project.

For reasons of expediency, you might be tempted to do things in your own way. Once you know HTML who needs Anakia, right? This is the incorrect approach but we will explore it so that the basic steps for updating your site on Jakarta become clearer.

Assuming your project is called myproject, here are steps you should follow:

1. Logon to the machine hosting the Jakarta web site.
2. Create a directory named myproject under the /www/jakarta.apache.org/ directory.
3. Copy your HTML files under the newly created directory.
4. That's it!

The new project's web-pages should be accessible under http://jakarta.apache.org/myproject.

The important point to remember is that you are responsible for updating your project pages. This statement remains true even if you switch to the recommended procedure described below.

If you decide to place your project's web pages under CVS control, then the pages should pertain to your project's CVS module and not to the jakarta-site2 module. For example, the contents of /www/jakarta.apache.org/regexp/CVS/Repository refer to jakarta-regexp/docs and in no way to the jakarta-site2 module. Ask for help if you don't see what we are talking about.

There are several problems with the do-it-your-way approach we have just outlined. First, the myproject pages are not linked to from the other Jakarta project pages. Your project is just dangling off Jakarta. Second, your web-pages do not follow the same look-and-feel as the other Jakarta projects. You can spend many hours trying to imitate the same look and feel. However, the Jakarta look-and-feel might change in the future. What will you do then? The solution is described below. Read on.

Check out the jakarta-site2 module into a directory that is "next" to your current project directory.

	cd /projects cvs -d /home/cvs login cvs -d /home/cvs co jakarta-site2 cvs -d /home/cvs co jakarta-velocity <-- example other project

Your directory structure should then look something like this:

	/projects /jakarta-site2 /jakarta-myproject /jakarta-velocity /jakarta-tomcat

The jakarta-site2 module has an /examples directory. Within there is a jakarta-myproject directory that you can copy into your /projects directory. This directory has everything that you need to get started with the documentation portion of your project. Essentially, it contains all of the files and configuration that is documented below.

Once you have copied the directory into /projects, you should read the instructions below to get a feeling for where everything is and how things are configured.

You should first create a directory structure within your project that can be used to store your documentation:

	/projects /jakarta-myproject/ /build.sh <-- Your Ant build.sh file /build.xml <-- Your Ant build.xml file /docs/ <-- This is where the generated .html files will go. Your images and other resources will also end up in here. /xdocs/ <-- This is where your source .xml files will go. /images/ <-- This is where your images will go. /stylesheets/ <-- This is where your project.xml and optionally, your style.vsl will go. /project.xml <-- Your project.xml file. See below. /velocity.properties <-- A copy of the velocity.properties file. See below.

Copy the project.xml file from the jakarta-site2/xdocs/stylesheets/ directory into your jakarta-myproject/xdocs/stylesheets/ directory and modify it as needed to reflect the navigation needs of your project. If you are going to provide links to other projects within the Jakarta project, make sure to make their href attribute based on the "document root". For example, if your project links to the Ant project, then the href should be something like this: href="/ant/index.html"

You will need to make a copy of the velocity.properties file from the jakarta- site2 module. Place it into the xdocs directory as outlined above. Within the file, you should modify the property shown below to point to the stylesheets directory within the jakarta-site2 directory. The path is relative to where the build.sh script is run from. This tells Velocity where to look for the style.vsl file. Since you want the same look and feel as the Jakarta website, you should at least start off by using this file.

	resource.loader.1.resource.path = ../jakarta-site2/xdocs/stylesheets

Assuming that you are using Ant as your build tool for your project, you should then be able to copy/paste the appropriate targets from the jakarta-site2/build.xml file into your own build.xml file for your project. You will need to make sure that the jar files in the jakarta-site2/lib directory are also added into your classpath in your build.sh script. The reason is that Ant does not have a way (that I know of) to add files to the classpath based on a conditional set of requirements. In other words, you want to allow people to build the rest of your project, but you do not want to require your users to have the jakarta-site2 module checked out in order to do so. You only want them to have to check out the jakarta-site2 module if they are going to build their documentation. Unfortunately, this isn't currently possible with Ant, therefore you need to specify the jakarta-site2 .jar files in the build.sh classpath using the examples below...

Below is the stuff you should add to your build.xml file. Please note that the path to the docs.src and docs.dest would be relative to the directory where the build.sh script is run from.

	<property name="docs.src" value="./xdocs"/> <property name="docs.dest" value="./docs"/> <target name="prepare"> <available classname="org.apache.velocity.anakia.AnakiaTask" property="AnakiaTask.present"/> </target> <target depends="prepare" name="prepare-error" unless="AnakiaTask.present"> <echo> AnakiaTask is not present! Please check to make sure that velocity.jar is in your classpath. </echo> </target> <target name="docs" depends="prepare-error" if="AnakiaTask.present"> <taskdef name="anakia" classname="org.apache.velocity.anakia.AnakiaTask"/> <anakia basedir="${docs.src}" destdir="${docs.dest}/" extension=".html" style="./site.vsl" projectFile="stylesheets/project.xml" excludes="**/stylesheets/** empty.xml" includes="**/*.xml" lastModifiedCheck="true" velocityPropertiesFile="${docs.src}/velocity.properties"> </anakia> <copy todir="${docs.dest}/images" filtering="no"> <fileset dir="${docs.src}/images"> <include name="**/*.gif"/> <include name="**/*.jpeg"/> <include name="**/*.jpg"/> </fileset> </copy> </target>

Below is an example of what your build.sh file should look like. What is important to note is that it is building up the CLASSPATH to find the .jar files for Anakia. Because it adds itself to the CLASSPATH after you do, any .jar files in your project that duplicate the .jar files needed by Anakia will take precedence. So, if there are issues with running Anakia with a combined classpath, you can opt to make a separate build script for running Anakia with its own CLASSPATH.

	#!/bin/sh if [ "$JAVA_HOME" = "" ] ; then echo You must set JAVA_HOME to point at your Java Development Kit directory exit 1 fi # convert the existing path to unix if [ "$OSTYPE" = "cygwin32" ] || [ "$OSTYPE" = "cygwin" ] ; then CLASSPATH=`cygpath --path --unix "$CLASSPATH"` fi # Add in your .jar files first for i in ./lib/*.jar do CLASSPATH=$CLASSPATH:"$i" done # Add in the jakarta-site2 library files for i in ../jakarta-site2/lib/*.jar do CLASSPATH=$CLASSPATH:"$i" done # convert the unix path to windows if [ "$OSTYPE" = "cygwin32" ] || [ "$OSTYPE" = "cygwin" ] ; then CLASSPATH=`cygpath --path --windows "$CLASSPATH"` fi BUILDFILE=build.xml #echo $CLASSPATH java $ANT_OPTS -classpath "$CLASSPATH" org.apache.tools.ant.Main \ -Dant.home=$ANT_HOME \ -buildfile ${BUILDFILE} \ "$@"

Now, in order to build your website, all you need to do is:

	cd jakarta-myproject ./build.sh docs

The documentation will then be generated into the jakarta-myproject/docs directory.

If you take a look at the project.xml file within your xdocs/stylesheets directory, you will notice that it is the side navigation portion of the website. If you want your project logo to appear in the upper right corner next to the Jakarta Project logo, then un-comment the <logo> tag and specify the path to the logo in your images directory or a full URI to your logo. If your project has its own navigation needs, simply modify the <menu> tags and place in your own navigation elements.

Within your xdocs directory is also a sample index.xml file. It shows the basic things that you need to modify to create your own page. You can embed whatever HTML you want into this file so long as it conforms to the XHTML specification (essentially, these are XML files so you need to embed XHTML in order for them to be parsed correctly). You can look at the other .xml files within the jakarta-site2 module for more examples of the different things you can do. If there are errors in your .xml file, they will be reported in the output of running your build.sh script.

The list of tags which you can use within your XML/XHTML file are documented on another page.

People who have accounts on apache.org can check in their changes to the jakarta-site2 module directly. If you get an error such as "Access denied: Insufficient Karma", then please send email to the general@jakarta.apache.org mailing list and we will grant you the appropriate access. If you do not have an account, then please feel free to send patches (against the .xml files and not the .html files!) to the general@jakarta.apache.org mailing list.

You should edit the .xml files and then run build.sh. After you have done that, you should check in both the .xml files and the .html files. Once your changes have been checked in, you can do the following:

	cd /www/jakarta.apache.org cvs update index.html cd site cvs update

This will cause the files checked into the jakarta-site2/docs directory to be checked out and updated on the live website.

If there are parts of this document that are confusing to you or there are errors in the Anakia portion of the jakarta-site2 module, please send feedback to the general@jakarta.apache.org mailing list. Please try to give a detailed description of what is confusing so that I can update the page to make things more clear.