Commit 07ce4e00 authored by Glenn Walbran's avatar Glenn Walbran

Backport build changes from 16.04

parent 30a7f25e
......@@ -5,3 +5,4 @@
/launchpad
/potfiles
/venv
/wheelhouse
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
......@@ -8,10 +7,11 @@ SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = build
MAHARA =
CLEAN = fr
PATCHED = de en nl
UNSUPPORTED =
TRANSLATIONS = $(CLEAN) $(PATCHED)
TRANSLATIONS = en de fr nl
# TRANSLATIONS_UNSUPPORTED = ja
# TODO: Building Japanese language PDFs with LaTeX is non-trivial and poorly documented.
# TODO: Complicating it with Sphinx has made it pretty much impossible. Good luck!
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
......@@ -43,12 +43,14 @@ clean:
-rm -rf $(BUILDDIR)/*
-rm -rf source/locales/*
# This is used by the build cronjob to checkout the correct manual version.
update:
git checkout .
git checkout $(MAHARA)_STABLE
git pull
fetchtranslations:
/bin/bash generate-mo-files.sh $(MAHARA)
/bin/bash get-localised-images.sh $(MAHARA)
preview:
$(SPHINXBUILD) -a -D language=en -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/en/$(MAHARA)
......@@ -56,76 +58,56 @@ preview:
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/en/$(MAHARA)."
@echo "The 'LANG' tokens in the crosslinks block have not been replaced with 'en' however."
html:
$(foreach TRANSLATION,$(TRANSLATIONS), \
html: fetchtranslations
@$(foreach TRANSLATION,$(TRANSLATIONS), \
sed -i 's/LANG/$(TRANSLATION)/g' source/mahara/links.html; \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images/ ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA); \
git checkout source/mahara/links.html \
;)
git checkout source/images
git checkout source/mahara/links.html; \
echo "---------------"; \
)
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html/<language>/$(MAHARA)."
dirhtml:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The dirhtml pages are in $(BUILDDIR)/dirhtml/<language>/$(MAHARA)."
singlehtml:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The singlehtml pages are in $(BUILDDIR)/singlehtml/<language>/$(MAHARA)."
pickle:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The pickle pages are in $(BUILDDIR)/pickle/<language>/$(MAHARA)."
json:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The json pages are in $(BUILDDIR)/json/<language>/$(MAHARA)."
htmlhelp:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp/<language>/$(MAHARA)."
qthelp:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp/<language>/$(MAHARA), like this:"
......@@ -135,11 +117,8 @@ qthelp:
devhelp:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished."
@echo "To view the help file:"
......@@ -147,80 +126,51 @@ devhelp:
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/Mahara"
@echo "# devhelp"
epub:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
epub: fetchtranslations
@$(foreach TRANSLATION,$(TRANSLATIONS), \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA); \
cp $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA)/Mahara.epub $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA)/Mahara.epub; \
rm -r $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA)/ \
;)
git checkout source/images
rm -r $(BUILDDIR)/epub/$(TRANSLATION)/$(MAHARA)/; \
echo "---------------"; \
)
@echo
@echo "Build finished. The epub files have been moved to $(BUILDDIR)/html/<language>/$(MAHARA)/Mahara.epub."
latex:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
latex: fetchtranslations
@$(foreach TRANSLATION,$(TRANSLATIONS), \
echo "Translation [$(TRANSLATION)]..."; \
sphinxlang=$(TRANSLATION) $(SPHINXBUILD) -a -D language=$(TRANSLATION) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
echo "---------------"; \
)
@echo
@echo "Build finished. The latex pages are in $(BUILDDIR)/latex/<language>/$(MAHARA)."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(foreach TRANSLATION,$(UNSUPPORTED), \
mkdir -p source/locales/$(TRANSLATION)/$(MAHARA)/LC_MESSAGES; \
cp -n /usr/share/locale-langpack/en_AU/LC_MESSAGES/sphinx.mo source/locales/$(TRANSLATION)/$(MAHARA)/LC_MESSAGES/sphinx.mo \
;)
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
/bin/bash convert_images_dpi.sh; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
cp patches/makesty.patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
cp patches/tex.patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/makesty.patch; \
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/tex.patch \
;)
$(foreach TRANSLATION,$(CLEAN), \
make -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf-ja \
;)
$(foreach TRANSLATION,$(PATCHED), \
cp patches/$(TRANSLATION).patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA); \
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/$(TRANSLATION).patch; \
make -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf-ja; \
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/$(TRANSLATION).patch \
;)
$(foreach TRANSLATION,$(TRANSLATIONS), \
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/tex.patch; \
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/makesty.patch; \
latexpdf: latex
@$(foreach TRANSLATION,$(TRANSLATIONS), \
echo "Translation [$(TRANSLATION)]..."; \
sed -i s/,dvipdfmx// $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/Mahara.tex; \
$(MAKE) PDFLATEX="xelatex -halt-on-error -file-line-error" -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf|grep -P -A2 ":[0-9]+:\ .*|Error:"; \
cp $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/Mahara.pdf $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA)/Mahara.pdf; \
rm -r $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/ \
;)
git checkout source/images
@echo "pdflatex finished; the PDF files have been moved to $(BUILDDIR)/html/<language>/$(MAHARA)/Mahara.pdf."
echo "---------------"; \
)
@echo
@echo "Build finished. The PDF files are in $(BUILDDIR)/latex/<language>/$(MAHARA)."
@echo " NOTE: Japanese language PDF, if built, probably failed. This is expected for now."
text:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The text pages are in $(BUILDDIR)/text/<language>/$(MAHARA)."
man:
$(foreach TRANSLATION,$(TRANSLATIONS), \
git checkout source/images ; \
cp -ra localeimages/$(TRANSLATION)/* source/images ; \
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man/$(TRANSLATION)/$(MAHARA) \
;)
git checkout source/images
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man/<language>/$(MAHARA)."
......
The Mahara User Manual is written using [reStructuredText](http://docutils.sourceforge.net/rst.html)
and built using [Sphinx](http://www.sphinx-doc.org/).
Contributing to and building the documentation
==============================================
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.
apt-get install python-virtualenv texlive-xetex texlive-lang-all texlive-fonts-extra
Clone this git repository, and in its directory, start the environemnt and install the
requirements:
virtualenv venv
. venv/bin/activate
pip install -r requirements.txt
Then you can build the documentation with the make command:
make html latexpdf
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!
Deploying to a server that can't install remote packages
========================================================
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.
For instance, on your workstation:
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
#!/bin/bash
dir=$(dirname $0)
cd $dir
if ! which git >/dev/null; then
echo "Please install git before continuing."
exit 1
fi
if [ -z $1 ]; then
branch=$(git symbolic-ref HEAD|sed "s/refs\/heads\///")
echo "Mahara version not specified; determining from user-manual git branch: $branch"
version=$(echo $branch|sed "s/_.*//")
# Could do with a better test here, but for now this works:
if [ ! "$(echo $version|grep ^1)" = "$version" ]; then
echo "Failed to find a version."
exit 1
fi
echo "Obtained version: $version"
else
version=$1
fi
if which bzr >/dev/null; then
echo "Starting import of translations..."
echo "Starting import of translations..."
else
echo "Please install bzr before continuing."
exit
echo "Please install bzr before continuing."
exit 1
fi
if [ ! -d launchpad ]; then
echo "Checking out the launchpad .po files"
bzr checkout lp:~mahara-lang/mahara-manual/$1_STABLE-export launchpad && cd launchpad && ..
else
echo "Updating .po collection from launchpad"
cd launchpad && bzr switch $1_STABLE-export --force && cd ..
echo "Checking out the launchpad .po files"
bzr checkout lp:~mahara-lang/mahara-manual/${version}_STABLE-export launchpad || exit 1
elif [ -z $(find launchpad/.bzr/checkout/lock -type d -mmin 120 |head -1) ]; then
# Re-fetch from Launchpad if more than eight hours old, so that it
# skips during a dev or testing session, but a daily cron always fetches.
echo "Updating .po collection from launchpad"
cd launchpad
bzr switch --force ${version}_STABLE-export
cd ..
fi
#echo "Cleaning up from last time"
......@@ -22,10 +47,14 @@ fi
if [ $(ls launchpad/potfiles/ -1A | wc -l) -gt 0 ]; then
for dir in launchpad/potfiles/*; do
echo "Creating $dir .mo files"
for file in $dir/*; do
mofile="$(basename $file | sed s%.po$%%)/LC_MESSAGES$(echo $dir | sed s%launchpad/potfiles%%).mo"
mkdir -p "source/locales/$(basename $file | sed s%.po$%%)/LC_MESSAGES"
msgfmt "$dir/$(basename $file)" -o "source/locales/$mofile"
done
for file in $dir/*; do
mofile="$(basename $file | sed s%.po$%%)/LC_MESSAGES$(echo $dir | sed s%launchpad/potfiles%%).mo"
mkdir -p "source/locales/$(basename $file | sed s%.po$%%)/LC_MESSAGES"
msgfmt "$dir/$(basename $file)" -o "source/locales/$mofile"
done
done
fi
#We always exit with success so that failing to fetch translations does not prevent
#the english(default) doc build
exit 0
from __future__ import unicode_literals
# -*- coding: utf-8 -*-
#
# Mahara documentation build configuration file, created by
......@@ -21,7 +23,21 @@ import sys, os
# -- General configuration -----------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
needs_sphinx = '1.0'
needs_sphinx = '1.4'
gettext_additional_targets = ['image', 'figure']
# NOTE:
# figure_language_filename can't be changed from the default in reality, since
# {root} is the full filesystem path of the image file, not the relative path.
# Don't ask me why. The only real option for images is to be, for example:
#
# images/foo.de.png
#
# The problem with that is when you specify images/foo.* as your image file in
# a figure directive, Sphinx will find both images/foo.png and images/foo.de.png
# and pick the first one, which is often wrong (especially if it's the en build).
figure_language_filename = "{root}.{language}{ext}"
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
......@@ -177,57 +193,63 @@ htmlhelp_basename = 'Maharadoc'
# -- Options for LaTeX output --------------------------------------------------
# The paper size ('letter' or 'a4').
latex_paper_size = 'a4'
# The font size ('10pt', '11pt' or '12pt').
#latex_font_size = '10pt'
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Mahara.tex', u'Mahara user manual',
u'Catalyst IT and others', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
latex_logo = 'images/mahara_logo.png'
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
LATEX_MAINFONT = 'FreeSerif'
LATEX_BABEL = '\\usepackage{babel}'
LATEX_TITLE = "Mahara user manual"
LATEX_AUTHOR = "Catalyst IT and others"
language = os.environ.get('sphinxlang', 'en')
if language == 'ja':
LATEX_MAINFONT = 'WenQuanYi Micro Hei'
LATEX_TITLE = "Mahara ユーザマニュアル"
LATEX_AUTHOR = "Catalyst IT および他の著者。"
elif language.startswith('zh'):
LATEX_MAINFONT = 'WenQuanYi Micro Hei'
elif language == 'nl':
LATEX_BABEL = '\\usepackage[dutch]{babel}'
LATEX_TITLE = "Mahara handleiding"
LATEX_AUTHOR = "Catalyst IT en andere autheurs."
elif language == 'de':
LATEX_BABEL = '\\usepackage[german]{babel}'
LATEX_TITLE = "Mahara Benutzerhandbuch"
LATEX_AUTHOR = "Catalyst IT und andere Autoren"
elif language == 'fr':
LATEX_BABEL = '\\usepackage[frenchb]{babel}'
LATEX_TITLE = "Manuel de l'Utilisateur de Mahara"
LATEX_AUTHOR = "Catalyst IT et d'autres auteurs"
# Additional stuff for the LaTeX preamble.
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title, author, documentclass [howto/manual]).
latex_documents = [
('index', 'Mahara.tex', LATEX_TITLE, LATEX_AUTHOR, 'manual')
]
latex_preamble = '''
LATEX_PREAMBLE = '''
\\RequirePackage{ifxetex}
\\RequireXeTeX
\\usepackage{xltxtra} %xltxtra = fontspec, xunicode, etc.
\\usepackage{xltxtra}
\\usepackage{verbatim}
\\usepackage{url}
\\usepackage{fontspec}
\\setmainfont{FreeSerif}
\\setmainfont{%s}
\\usepackage{amsmath}
\\usepackage{amsfonts}
\\usepackage{xunicode}
'''
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
''' % (LATEX_MAINFONT)
latex_elements = {
'papersize': 'a4',
'pointsize': '10pt',
'inputenc': '',
'babel': '\usepackage[frenchb]{babel}'
'babel': LATEX_BABEL,
'preamble': LATEX_PREAMBLE,
}
......@@ -280,5 +302,4 @@ epub_copyright = u'2011-2016 Dual licensed under Creative Commons BY-SA 3.0 unpo
# Allow duplicate toc entries.
#epub_tocdup = True
language = 'en'
locale_dirs = ["locales/"]
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