Skip to content

Commit 627a200

Browse files
IvozIvoz
committed
Major reshuffle, reproduceable i18n
- Cleaned up folder structure. All normal source now just resides in source folder, all build files reside in _build. - Configuration is now just in source/conf.py - fabfile updated to allow for reproduceable and maintainable i18n. - The translations in `source/_locales/de/LC_MESSAGES/` should be reworked into the proper files under the `source/locale/` folder. - This is following the i18n practices given by http://sphinx-doc.org/latest/intl.html and https://pypi.python.org/pypi/sphinx-intl#quickstart-for-sphinx-translation - Introductory index.html made slightly fancier!
1 parent 73b7d3d commit 627a200

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

52 files changed

+1447
-72
lines changed

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,6 @@
22
._*
33
*.pyc
44

5-
docs/_build
6-
docs/*/_build
5+
_build
6+
source/locale/*/*/*.mo
7+
source/_locales/*/*/*.mo

‎README.rst‎

Lines changed: 24 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,9 @@ need to have the following Python packages installed:
3434
- Pygments
3535
- Sphinx
3636
- Fabric
37+
- sphinx-intl
38+
39+
You can install these with pip using ``pip install -r requirements.txt``
3740

3841
Build
3942
=====
@@ -44,10 +47,10 @@ easy. The following commands have to be executed in the ``docs`` directory.
4447
If you just want to render the HTML version, it's sufficient to run
4548

4649
.. code:: bash
47-
50+
4851
fab build
4952
50-
This will create a directory ``_build`` inside the ``docs`` directory,
53+
This will create a directory ``_build``,
5154
containing the HTML version.
5255

5356
Other `builders <http://sphinx.pocoo.org/builders.html#builders>`_ can be
@@ -57,7 +60,22 @@ tutorial into a single HTML file.
5760
.. code:: bash
5861
5962
fab build:singlehtml
60-
63+
64+
Translatation
65+
=============
66+
67+
1. Translation (pot) templates must be built or updated - ``fab gen_pots``
68+
2. Templates must merged/built into po translation files - ``fab update_pos:de``
69+
70+
.. note:: Both 1 and 2 can be done with ``fab update_pos``
71+
72+
3. po files must be checked and translated correctly
73+
4. ``fab build`` will compile po files, and build the docs for each language
74+
75+
.. note:: only po files should be committed to version control. pot and mo
76+
files are built automatically.
77+
78+
6179
Deploy
6280
======
6381

@@ -69,8 +87,9 @@ process, you can use the fabric target ``setup``.
6987
7088
fab setup
7189
72-
This creates a clone of the repository inside the ``_build`` folder. You can
73-
now run ``fab build``, change into ``docs/_build/html``, commit and push.
90+
This recreates the ``_build/html`` folder by building the project, while the
91+
folder is cloned to the ``gh-pages`` branch. You can simple cd into the folder
92+
thereafter and push new updates, or use ``fab build`` to rebuild it.
7493

7594
License
7695
=======

docs/_static/index.html renamed to _static/index.html

File renamed without changes.

‎docs/en/conf.py‎

Lines changed: 0 additions & 13 deletions
This file was deleted.

‎docs/fabfile.py‎

Lines changed: 0 additions & 51 deletions
This file was deleted.

‎fabfile.py‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
from fabric.api import local
2+
from fabric.context_managers import lcd
3+
import os
4+
5+
6+
BASE_DIR = os.path.realpath(os.path.dirname(__file__))
7+
BUILD_DIR = os.path.join(BASE_DIR, '_build')
8+
SOURCE_DIR = os.path.join(BASE_DIR, 'source')
9+
LOCALE_DIR = os.path.join(SOURCE_DIR, 'locale',
10+
'%s', 'LC_MESSAGES')
11+
LANGUAGES = {'en', 'de'}
12+
MAIN_TARGET = 'html'
13+
REPOSITORY = 'git@github.com:OpenTechSchool/python-beginners.git'
14+
15+
16+
def setup():
17+
clean()
18+
target_dir = os.path.join(BUILD_DIR, MAIN_TARGET)
19+
local('mkdir -p %s' % target_dir)
20+
local('git clone %s -b %s --single-branch %s' %
21+
(REPOSITORY, 'gh-pages', target_dir))
22+
with lcd(target_dir):
23+
local('rm -rf ./*')
24+
local('touch .nojekyll')
25+
build()
26+
27+
28+
def build(target=MAIN_TARGET):
29+
for language in LANGUAGES:
30+
build_language(language, target)
31+
if 'html' in target:
32+
static_files = os.path.join(BASE_DIR, '_static', '*')
33+
target_dir = os.path.join(BUILD_DIR, target)
34+
local('cp %s %s' % (static_files, target_dir))
35+
36+
37+
def build_language(language, target=MAIN_TARGET):
38+
if os.path.isdir(LOCALE_DIR % language):
39+
compile_pos(language)
40+
args = [
41+
'sphinx-build',
42+
'-b', # builder type
43+
target,
44+
'-d', # doctree path
45+
os.path.join(BUILD_DIR, 'doctrees'),
46+
'-D',
47+
'language=%s' % language,
48+
SOURCE_DIR,
49+
os.path.join(BUILD_DIR, target, language), # output path
50+
]
51+
local(' '.join(args))
52+
53+
54+
def update_pos(language=None):
55+
"""Update .po files if source has changed"""
56+
gen_pots(language)
57+
if language is None:
58+
lang_set = LANGUAGES - {'en'}
59+
else:
60+
lang_set = language
61+
for language in lang_set:
62+
args = [
63+
'sphinx-intl update',
64+
'-l %s ' % language,
65+
'-p',
66+
os.path.join(BUILD_DIR, 'locale', language),
67+
'-c',
68+
os.path.join(SOURCE_DIR, 'conf.py'),
69+
]
70+
local(' '.join(args))
71+
72+
73+
def compile_pos(language):
74+
"""Compile .pos into .mos"""
75+
args = [
76+
'sphinx-intl build',
77+
'-l %s' % language,
78+
'-c',
79+
os.path.join(SOURCE_DIR, 'conf.py'),
80+
]
81+
local(' '.join(args))
82+
83+
84+
def gen_pots(language=None):
85+
"""Generate .pots from sphinx source files"""
86+
if language is None:
87+
lang_set = LANGUAGES - {'en'}
88+
else:
89+
lang_set = language
90+
for language in lang_set:
91+
args = [
92+
'sphinx-build',
93+
'-b gettext',
94+
'-D language=%s' % language,
95+
SOURCE_DIR,
96+
os.path.join(BUILD_DIR, 'locale', language),
97+
]
98+
local(' '.join(args))
99+
100+
101+
def clean(target=MAIN_TARGET):
102+
local('rm -rf %s' % os.path.join(BUILD_DIR, target))

‎requirements.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,3 +2,4 @@ Fabric
22
Pygments
33
Sphinx
44
docutils
5+
sphinx-intl

docs/en/locale/de/LC_MESSAGES/pybeginners.mo renamed to source/_locales/de/LC_MESSAGES/pybeginners.mo

File renamed without changes.

docs/en/locale/de/LC_MESSAGES/pybeginners.po renamed to source/_locales/de/LC_MESSAGES/pybeginners.po

File renamed without changes.

docs/en/_static/spoilers.js renamed to source/_static/spoilers.js

File renamed without changes.

0 commit comments

Comments
 (0)