Building documentation

As bookkeeper is a subproject of zookeeper, we use the Apache cms system also used by zookeeper to generate our website and documentation.

To get CMS and the zookeeper source, run the following:

$ svn co https://svn.apache.org/repos/asf/zookeeper/site/trunk zookeeper-site
$ svn co https://svn.apache.org/repos/infra/websites/cms cms

Generate the documentation with:

$ cms/build/build_site.pl --source-base zookeeper-site/ --target-base output

There are three locations for bookkeeper documentation within the zookeeper-site tree.

• zookeeper-site/templates/bookkeeper (svn link to https://svn.apache.org/repos/asf/zookeeper/bookkeeper/site/templates): This contains the navigation links and template for all pages.
• zookeeper-site/content/bookkeeper (svn link https://svn.apache.org/repos/asf/zookeeper/bookkeeper/site/content): The content of the main part of the bookkeeper site
• zookeeper-site/content/bookkeeper/docs/trunk (svn link https://svn.apache.org/repos/asf/zookeeper/bookkeeper/trunk/doc): The trunk documentation in the source tree. To test doc generation without having to commit to trunk, just mv this out of the way and create your own symlink to trunk in your local bookkeeper source tree.

Making modifications

Modifications to the site doesn't require a JIRA, though modifications to the source tree (i.e. docs/trunk) does. When you make a modification to the bookkeeper site, they will not be automatically built. First you need trigger a build. To do this, commit a change to https://svn.apache.org/repos/asf/zookeeper/site/trunk/build_trigger. This triggers a svn trigger which triggers the cms system.

The cms system will put the modifications in staging; http://zookeeper.staging.apache.org.

See http://www.apache.org/dev/cms.html for details on how to publish the staged site.

Generating documentation for release

When making a release, you need to generate the version's documentation and then copy it into zookeeper-site/content/bookkeeper/docs. To do this:

1. Copy the documentation directory from the release tag to zookeeper-site/content/bookkeeper/docs.

   $ cp -r bookkeeper-svn/tags/release-4.1.0/doc/ zookkeeper-site/content/bookkeeper/docs/r4.1.0

   Add to subversion.
2. Generate the javadoc for the release. In bookkeeper-svn/tags/release-4.1.0/ run mvn javadoc:aggregate. This will create bookkeeper-svn/tags/release-4.1.0/target/site/apidocs. Copy this to zookeeper-site/content/bookkeeper/docs/r4.1.0 and add it to subversion.
3. Modify zookeeper-site/content/bookkeeper/docs/r4.1.0/index.textile to point to the javadoc and release notes. See zookeeper-site/content/bookkeeper/docs/r4.0.0/index.textile for an example of how to do this.
4. Add the release to zookeeper-site/content/bookkeeper/releases.textile.
5. Go through the staging/publish sequence from above. Obviously the version numbers will change to each release.