Page History

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

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

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

Generate the documentation with:

$ cms/build/build_site.pl --source-base zookeeperbookkeeper-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):^{Image Removed} 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):^{Image Removed} 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):^{Image Removed} 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^{Image Removed}. This triggers a svn trigger which triggers the cms system.

The cms system will put the modifications in staging; http://zookeeper.staging.apache.org^{Image Removed}.

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

You can view the generates site by running the python SimpleHTTPServer and navigating to http://localhost:8000/.

/tmp/output$ python -m SimpleHTTPServer
Serving HTTP on 0.0.0.0 port 8000 ...
...
...

Making modifications

Modifications to the site doesn't require a JIRA, though if it is a large modification you should create one. When you make a modification to the bookkeeper site and submit it through subversion, they will be automatically built.

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

You'll need the CMS bookmarklet to publish the site. See the CMS documentation for details.

Generating documentation for release

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

1. Check out the git release tag for the release.

   Code Block
   bookkeeper$ git checkout release-4.3.0

2. Copy the documentation directory to bookkeeper-site/content/docs.

   Code Block
   bookkeeper$ cp -r doc/ ../bookkeeper-site/content/docs/r4.3.0

   Add to subversion.

3. Generate the javadoc for the release and copy it to the site.

   Code Block
   bookkeeper$ mvn javadoc:aggregate ... ... bookkeeper$ cp -r target/site/apidocs ../bookkeeper-site/content/docs/r4.3.0

4. Add the new release docs directory to subversion.
5. Modify bookkeeper-site/content/docs/r4.3.0/index.textile to point to the javadoc and release notes. See bookkeeper-site/content/docs/r4.0.0/index.textile for an example of how to do this.

6. Modify bookkeeper-site/templates/skeleton.html and and a link for the release documentation.

   Code Block
   language diff
   <li class="dropdown"> <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">Documentation<span class="caret"></span></a> <ul class="dropdown-menu" role="menu"> <li><a href="/docs/trunk">Trunk</a></li> + <li><a href="/docs/r4.3.0">Release 4.3.0</a></li> <li><a href="/docs/r4.2.3">Release 4.2.3</a></li>

7. Add the release to bookkeeper-site/content/releases.textile.
8. Go through the staging/publish sequence from above. Obviously the version numbers will change for each release.

...