Commit 09bd7526 authored by Glenn Walbran's avatar Glenn Walbran
Browse files

Dockerize the manual build process

It should be easy for anyone to build the Mahara docs. Docker gives us that way.

Added a Dockerfile to create a docbuilder and updated the
parent adf72073
FROM debian:stable
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 \
&& echo "Testing sphinx installation" \
&& sphinx-build --version
The Mahara User Manual is written using [reStructuredText](
and built using [Sphinx](
# Building Mahara docs
The Mahara User Manual is:
Contributing to and building the documentation
- written using [reStructuredText](
- built using [Sphinx](
- 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
## 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]( 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](
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
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
And on the server:
cd /wherever/your/manual/is/installed
. venv/bin/activate
pip install --no-index --find-links=/tmp/wheelhouse
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment