This documentation is built using Sphinx with the sphinx-rtd-theme.

Both Python 2.7 and 3.5+ should work; 3.5+ is preferred.


To build the HTML
-----------------

Make sure you have a current version of sphinx-rtd-theme installed:

  $ pip3 install sphinx sphinx-rtd-theme

  Note: If you're on Debian Stretch or some version of Ubuntu, this will
  silently install into ~/.local, leaving the sphinx-build binary in
  ~/.local/bin, which is not on your path. One workaround (untested) is to run
  pip3 as root, which violates principle of least-privilege. A better
  workaround, assuming you can write to /usr/local, is to add the undocumented
  and non-standard --system argument to install in /usr/local instead. (This
  matches previous pip behavior.) See: https://bugs.debian.org/725848

Then:

  $ make

The HTML files are copied to ../doc with rsync. Anything that should not be
copied should be listed in RSYNC_EXCLUDE.

There is also a "clean" target that removes all the derived files as well as
everything in ../doc.


Publishing to the web
---------------------

If you have write access to the repository, you can update the web
documentation (i.e., http://hpc.github.io/charliecloud).

Normally, ../doc is normal directory that is ignored by Git. To publish to the
web, that diretory needs to contain a Git checkout of the gh-pages branch (not
a submodule). To set that up:

  $ rm -Rf doc
  $ git clone git@github.com:hpc/charliecloud.git doc
  $ cd doc
  $ git checkout gh-pages

To publish:

  $ make web

It sometimes takes a few minutes for the web pages to update.
