Status
colour Yellow title outdated

See Release Procedure for a more up to date version on how the docs can be uploaded

Releasing Publican Documentation from Apache CloudStack

...

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

Note that we're also assuming that anyone releasing the docs is a committer with rights to make an SVN commit. It could be done via anonymous Apache CMS or a SVN diff, but might be a little tricky.

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:

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

...

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.

Note that you need to clean out the doc/tmp directory after each guide is built.

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

...

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.

...

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

Commit to SVN

Once you've copied over the docs, move to the top-level directory for your SVN tree (like {~/src/web/cloudstack}) and run:

svn status

If everything looks good, then go ahead and commit:

svn ci -m "Committing documentation to the Web site for X.X.X release."

Naturally, you'll replace X.X.X with the appropriate version.

You can see whether the builds are successful here:

http://ci.apache.org/builders/cloudstack-site-staging/

Now it's time to look at staging and see if all looks well there. Go to http://cloudstack.staging.apache.org/docs/ and verify that the docs have shown up there.

Note that this may take a little while.

If all's well there, then you can commit the documentation:

curl -sL http://s.apache.org/cms-cli | perl

You will be prompted for the project name (CloudStack) and your username and password, as well as a number of other questions. You can safely say "no" to previewing, etc.

It may take a few minutes for the changes to show up on the live site.