How To Build Scarab Docs

The Scarab documenation is written using both xdoc and docbook formats. This documentation is generated by Maven. If you haven't used Maven before, follow the Getting Started directions.

The documentation is published by committing it to CVS in a seperate project called "scarab-gen".

Generating Maven Managed Docs

Documentation should all be written in the xdoc format, and stored under the /xdocs directory. When you are ready to generate the documentation, you can run Maven's site generation goal via 'maven site'. If you don't want to bother to run the unit tests, then run 'maven site -Dmaven.test.skip=true'. This will generate all the site documentation, as well as the FAQ, Javadocs, and various code analysis reports in the directory "/target/docs".

We use a Tasks plugin from Maven-Plugins to generate the roadmap document. This plugin should download automatically and install. If not, look at the directions here.

We use a Findbugs plugin from Maven-Plugins to look for common errors. This plugin should download automatically and install. If not, look at the directions here.

We use a StatCVS plugin from StatCVS to generate statistics on CVS. This plugin should download automatically and install. It requires CVS executable to be in your path. If you have TortoiseCVS installed on windows, then just add that directory to your path! The CVS.exe in the TortoiseCVS directory works fine.

Committing Maven Managed Docs

By default, Scarab is set up to ignore any files in the /target directory. So, to commit updated documentation, instead we use another project called "Scarab-Gen". This allows us to only have to deal with committing update documentation when we are actively working with the documents, and allows most developers to not have to check out from CVS multiple megabytes of documentation that they can either browse online, or generate for themselves.

First check out the "scarab-gen" project from CVS. This project has all the same permissions etc as the main Scarab project itself. By default, Scarab expects the scarab-gen and scarab projects to be at the same level in the directory structure. For example on Windows: 

		c:\java\scarab
		c:\java\scarab-gen
If not, update the scarab.docs.home property in project.properties.

If you are updating the HEAD version of the documentation, run then run Maven: 

		maven scarab:deploy_docs_head
to copy $SCARAB_HOME/target/docs/ to $SCARAB_GEN_HOME/www/head/. This also blanks out some of the commonly changed data so that when you commit to CVS you don't have to update every single file just because the Javadoc timestamp changed.

If you are cutting a release, then having timestamps etc is okay. Instead generate the documentation, then copy the documentation from $SCARAB_HOME/target/docs/ to $SCARAB_GEN_HOME/www/{betarelease}/. So, for beta19, you would copy to $SCARAB_GEN_HOME/www/b19/.

When you commit your new code you may need to do it in chunks. CVS can timeout if you attempt to commit everything all at once as the documentation is quite large.