Commit 6fbfe941 authored by Kristina Hoeppner's avatar Kristina Hoeppner

Merge branch 'docker-build' into 'master'

Dockerize the manual build process

See merge request !5
parents 68da3203 c25374de
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"]
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
Markdown is supported
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