Building the website and documentation

Apache Bookkeeper uses the Apache CMS system to generate our website and documentation.

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

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

Generate the documentation with:

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

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.

   bookkeeper$ git checkout release-4.3.0

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

   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.

   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.

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