Skip to content
GitLab
Menu
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in
Toggle navigation
Menu
Open sidebar
user-manual
manual-build
Commits
6fbfe941
Commit
6fbfe941
authored
Feb 24, 2020
by
Kristina Hoeppner
Browse files
Merge branch 'docker-build' into 'master'
Dockerize the manual build process See merge request
!5
parents
68da3203
c25374de
Changes
2
Hide whitespace changes
Inline
Side-by-side
Dockerfile
0 → 100644
View file @
6fbfe941
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
View file @
6fbfe941
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
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment