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

Prerequisites
-------------

  * Python 3.5+ or 2.7; 3.5+ is preferred
  * Sphinx 1.4.9+
  * docutils 0.13.1+
  * sphinx-rtd-theme 0.2.4+

Older versions of Sphinx and sphinx-rtd-theme may work but are untested.


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

Install Sphinx, docutils, and sphinx-rtd-theme:

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