Merge branch 'docker-build' into 'master'

Dockerize the manual build process

See merge request !5

Dockerfile

+FROM debian:stable
+
+ARG IMAGE_UID=1000
+ARG IMAGE_GID=1000
+
+ADD requirements.txt /tmp/requirements.txt
+
+RUN set -o errexit -o nounset \
+    && groupadd --system --gid $IMAGE_GID docbuilder \
+    && useradd --system --gid docbuilder --uid $IMAGE_UID --shell /bin/bash --create-home docbuilder \
+    && apt-get update \
+    && apt-get install -y python3-pip make git bzr gettext rsync \
+    && pip3 install -r /tmp/requirements.txt
+
+USER docbuilder
+
+# Create docbuilder/source volume
+# We expect this to be volume mounted to supply the document source files
+VOLUME "/home/docbuilder/source"
+WORKDIR /home/docbuilder/source
+
+RUN set -o errexit -o nounset \
+    && mkdir -p /home/docbuilder/.ssh \
+    && chown docbuilder:docbuilder /home/docbuilder/.ssh \
+    && chmod 700 /home/docbuilder/.ssh \
+    && echo "Testing sphinx installation" \
+    && sphinx-build --version
+
+ENTRYPOINT ["make"]

README.md

-The Mahara User Manual is written using [reStructuredText](http://docutils.sourceforge.net/rst.html)
-and built using [Sphinx](http://www.sphinx-doc.org/).
+# Building Mahara docs
 
+The Mahara User Manual is:
 
-Contributing to and building the documentation
-==============================================
+- written using [reStructuredText](http://docutils.sourceforge.net/rst.html)
+- built using [Sphinx](http://www.sphinx-doc.org/)
+  - with a docker builder
 
-To get started, use a Python virtual environment to install the stuff in `requirements.txt`.
-You'll also need a fairly recent distribution of TeX Live in order to render PDFs properly.
-Ubuntu 16.04 ships with TeX Live 2015 which includes XeTeX, which handles Unicode and
-OpenType fonts properly, and the language metrics (hyphenation etc.) that Sphinx uses to
-build translations.
 
-Ubuntu 16.04 minimum packages for html doc build:
+# Quickstart
 
-    apt-get install python-virtualenv make git bzr gettext
+Run one of the commands below to build the docs. The first command only builds english.
+The second builds all translations(and takes longer).
 
-additional Ubuntu 16.04 packages required for pdf doc build:
+```
+  docker run -v $(pwd)/:/home/docbuilder/source mahara/docbuilder TRANSLATIONS=en html
+  docker run -v $(pwd)/:/home/docbuilder/source mahara/docbuilder html
+```
 
-    apt-get install texlive-xetex texlive-latex-recommended texlive-fonts-recommended texlive-fonts-extra texlive-latex-extra
-    apt-get install texlive-lang-french texlive-lang-german texlive-lang-european
+The built docs will be in the `build/html` directory(on your host machine.
 
-Clone this git repository, and in its directory, start the environemnt and install the
-requirements:
+## Pre-requisites
 
-    virtualenv venv
-    . venv/bin/activate
-    pip install -r requirements.txt
+### Docker docbuilder
 
-Then you can build the documentation with the make command. Some common examples:
+[Docker](https://docker.com) needs to be available on your workstation.
 
-    make html                     # html for languages: en de fr nl
-    make TRANSLATIONS=en html     # html for en only
-    make TRANSLATIONS=en latexpdf # pdf for en only
+If Docker is not already available it needs to be installed and configured before
+you continue.
 
-Have a look at the
-[Hitchhiker's Guide to Python](http://docs.python-guide.org/en/latest/dev/virtualenvs/)
-tutorial for more information about how to use Python virtual environments; Don't panic,
-it's easy!
+If docker is available you can build the docbuilder image on Linux with:
 
-Deploying to a server that can't install remote packages
-========================================================
+```
+cd manual-build
+docker build --build-arg IMAGE_UID=`id -u` --build-arg IMAGE_UID=`id -g` --tag mahara/docbuilder .
+```
 
-To do this, make a wheelhouse (a directory of pre-compiled Python packages) and copy it over
-to your server, then on the server tell pip (in the virtual environment) to install them.
+The `mahara/docbuilder` image is based on a debian docker image with additional
+packages that are required for building the docs installed. Using a docker image
+for this makes it easy to get going with the same build environment as used by
+mahara.org.
 
-For instance, on your workstation:
+The image is also made so that the default user has the same UID:GID as the current
+system user. This is so that the built files are owned by the current user on the
+host machine(otherwise they might be owned by root).
 
-    pip wheel -w /tmp/wheelhouse -r requirements.txt
-    rsync -avz /tmp/wheelhouse my.server.com:/tmp/
-
-And on the server:
-
-    cd /wherever/your/manual/is/installed
-    . venv/bin/activate
-    pip install --no-index --find-links=/tmp/wheelhouse