Releasing Publican Documentation from Apache CloudStack

This page is a supplement to the main release procedure. The release manager may or may not also be the docs release manager. Note that this is a rough draft at the moment based on one release.

Prerequisites to Building and Publishing Documentation

You'll need (at least) three things to build and publish the documentation:

• The source for the documentation for the version of Apache CloudStack that is being published.
• The SVN tree for the Apache CloudStack Web site.
• A working Publican install with the Apache CloudStack branding package installed.
• Any dependencies implied by the above (SVN, Git, etc.)

The Apache CloudStack documentation requires Publican to build and (of course) the source code to the documentation itself. You can use the source tarball from a release once it's been approved via the VOTE or use source from Git.

You'll also need a checkout of the Web site via SVN. If you don't have this already, you'll need to get it, like so:

co svn https://svn.apache.org/repos/asf/cloudstack/

Note that both the SVN tree and Git tree are "cloudstack" so you probably don't want to check out the SVN tree in the same directory as the CloudStack directory. (Plus I don't think SVN would let you do that anyway.)

Suggestion: have a src directory under your $HOME directory and make a web or svn directory for the SVN tree.

You should have two source code directories: the Apache CloudStack source and the source for the Apache CloudStack Web site.

Building the Documentation

Use Publican to build the docs:

publican build --embedtoc --formats=html,epub,pdf,html-single --langs=en-US --publish --config=publican-adminguide.cfg

Replace the .cfg filename in "--config=" with the appropriate configuration file. We currently have four guides that need to be built with each release.

Replace the --langs= with the appropriate language(s) that should be built.

After you build and install the docs successfully, look under the publish directory under cloudstack/docs/ in the source tree.

You'll see directories for each language and version there, like en-US/4.0.2, and for each format (epub,html,html-single,pdf). You can (and should) look these over to make sure the build looks like what you expect it to.

"Install" the Documentation

Next you're going to add the current version of the documentation to the existing documentation. You'll stage this in the docsite directory, and then copy it over to the source tree where the site documentation actually lives.

publican install_book --site_config ~/src/web/cloudstack/docsite/acsdocs.cfg --config=publican-adminguide.cfg --lang en-US

Here ~/src/web/cloudstack/docsite/ is under the SVN tree in my environment. You'll need to sanity check the path for your own environment.

Note that you'll need to edit the acsdocs.cfg file to match your environment. Again, replace the variable (filename) after --config= to the appropriate value, like publican-install.cfg, etc. All of the appropriate config files are under the cloudstack/docs directory, just do 'ls *cfg' and you'll see all of them. Note that some of them are unusued.

Replace the --langs= with the appropriate language(s) that should be built.

Copy Documentation to the Site Tree

Next you'll need to copy the documentation from the docsite directory to the docs directory:

cp -R docsite/html/docs/* site/trunk/content/docs/.