README

This is the beaker-project.org web site.

To make changes, edit the relevant file and then run `make` to update
the generated files. You must have a clean, up-to-date checkout of the
master branch of Beaker's git for the documentation to be built. The
Makefile assumes Beaker can be found in ../beaker; if not, you must pass
the path in the BEAKER variable, e.g. `make BEAKER=/home/dan/beaker`.

Note that many parts of this web site are generated from elsewhere:

    * Some .html pages are generated from the corresponding .txt file in
      Markdown using Pandoc.
    * Some documentation is built using Sphinx from docstrings extracted
      from Beaker code.
    * Some documentation is built using Publican from DocBook sources
      included in Beaker.
    * Some shell scripts have a pretty documented version which is
      generated by shocco.


Publishing the web site
-----------------------

These instructions are only relevant to Beaker developers who have
access to publish to beaker-project.org.

Only publish changes that are already on the master branch. Make sure
your master branch is up to date:

    git checkout master
    git pull

Also make sure your 'published' branch is up to date. This is a special
branch for tracking the published version of the web site (including all
generated artefacts):

    git fetch beaker-project.org:/srv/www/beaker-project.org/git/ master:published

Build your changes:

    make publish

Now the 'published' branch has been updated. You may want to push it to
http://stage.beaker-project.org/ first, to make sure everything looks
okay:

    git push beaker-project.org:/srv/www/stage.beaker-project.org/git/ published:master

Once you're happy with it, push it live:

    git push beaker-project.org:/srv/www/beaker-project.org/git/ published:master