Added examples to i18n documentation, run doctests

.gitlab-ci.yml

@@ -1,28 +1,28 @@
 before_script:
 tests:
+    stage: test
     script:
-        - git submodule init
-        - git submodule update
         - virtualenv-3.4 env
         - source env/bin/activate
-        - cd src
-        - XDG_CACHE_HOME=/cache pip3 install -r requirements.txt -r requirements/dev.txt -r requirements/py34.txt
-        - flake8 --ignore=E123,F403,F401,N802,C901,W503 .
-        - isort -c -rc .
-        - python3 manage.py check
-        - make
-        - make compress
-        - coverage run -m py.test tests
+        - XDG_CACHE_HOME=/cache pip3 install -r src/requirements.txt -r src/requirements/dev.txt -r src/requirements/py34.txt -r doc/requirements.txt
+        - bash .travis.sh tests
     tags:
         - python3
-        - selenium
-build:
-    type: deploy
+doctests:
+    stage: test
     script:
-        - cd deployment/docker/standalone/
-        - docker login -u ciuser -p $DOCKERPW -e admin@rami.io docker.rami.io
-        - docker build -t pretix/standalone .
-        - docker tag -f pretix/standalone docker.rami.io/pretix/standalone:$CI_BUILD_REF_NAME
-        - docker push docker.rami.io/pretix/standalone:$CI_BUILD_REF_NAME
+        - virtualenv-3.4 env
+        - source env/bin/activate
+        - XDG_CACHE_HOME=/cache pip3 install -r src/requirements.txt -r src/requirements/dev.txt -r src/requirements/py34.txt -r doc/requirements.txt
+        - bash .travis.sh doctests
+    tags:
+        - python3
+style:
+    stage: test
+    script:
+        - virtualenv-3.4 env
+        - source env/bin/activate
+        - XDG_CACHE_HOME=/cache pip3 install -r src/requirements.txt -r src/requirements/dev.txt -r src/requirements/py34.txt -r doc/requirements.txt
+        - bash .travis.sh style
     tags:
-        - docker
+        - python3

.travis.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+set -e
+set -x
+
+echo "Executing job $1"
+
+if [ "$1" == "style" ]; then
+	cd src
+    flake8 --ignore=E123,F403,F401,N802,C901,W503,E402 .
+    isort -c -rc .
+fi
+if [ "$1" == "doctests" ]; then
+	cd doc
+	cat Makefile
+	make doctests
+fi
+if [ "$1" == "tests" ]; then
+	cd src
+	python manage.py check
+	make all compress
+	coverage run -m py.test tests && coveralls
+fi

.travis.yml

@@ -4,18 +4,13 @@ python:
     - "3.4"
 install:
     - pip install -U pip wheel setuptools
-    - pip install -q -U -r src/requirements.txt -r src/requirements/dev.txt -r src/requirements/py34.txt
-before_script:
-    - cd src
+    - pip install -q -U -r src/requirements.txt -r src/requirements/dev.txt -r src/requirements/py34.txt -r doc/requirements.txt
 script:
-    - flake8 --ignore=E123,F403,F401,N802,C901,W503,E402 .
-    - isort -c -rc .
-    - python manage.py check
-    - make
-    - make compress
-    - coverage run -m py.test tests
-after_success:
-    - coveralls
+    - bash .travis.sh $JOB
 cache:
     directories:
         - $HOME/.cache/pip
+env:
+    - JOB=style
+    - JOB=doctests
+    - JOB=tests

doc/development/implementation/i18n.rst

@@ -29,6 +29,73 @@ Whenever you interact with those fields, you will either provide or receive an i
 .. autoclass:: pretix.base.i18n.LazyI18nString
    :members: __init__, localize, __str__
 
+Usage
+-----
+
+The following examples are given to illustrate how you can work with ``LazyI18nString``.
+
+.. testsetup:: *
+
+   from pretix.base.i18n import LazyI18nString, language
+
+To create a LazyI18nString, we can cast a simple string:
+
+.. doctest::
+
+   >>> naive = LazyI18nString('Naive untranslated string')
+   >>> naive
+   <LazyI18nString: 'Naive untranslated string'>
+
+Or we can provide a dictionary with multiple translations:
+
+.. doctest::
+
+   >>> translated = LazyI18nString({'en': 'English String', 'de': 'Deutscher String'})
+
+We can use ``localize`` to get the string in a specific language:
+
+.. doctest::
+
+   >>> translated.localize('de')
+   'Deutscher String'
+
+   >>> translated.localize('en')
+   'English String'
+
+If we try a locale that does not exist for the string, we might get a it either in a similar locale or in the system's default language:
+
+.. doctest::
+
+   >>> translated.localize('de-AT')
+   'Deutscher String'
+
+   >>> translated.localize('zh')
+   'English String'
+
+   >>> naive.localize('de')
+   'Naive untranslated string'
+
+If we cast a ``LazyI18nString`` to ``str``, ``localize`` will be called with the currently active language:
+
+.. doctest::
+
+   >>> from django.utils import translation
+   >>> str(translated)
+   'English String'
+   >>> translation.activate('de')
+   >>> str(translated)
+   'Deutscher String'
+
+You can also use our handy context manager to set the locale temporarily:
+
+.. doctest::
+
+   >>> translation.activate('en')
+   >>> with language('de'):
+   ...     str(translated)
+   'Deutscher String'
+   >>> str(translated)
+   'English String'
 
 Forms
 -----