Like many teams developing large products, when developing an open source framework for the visual creation of iondv.framework web applications , the task was to document the capabilities of the system. First for yourself and new employees. Then for users. And at present, documentation is an important means of promoting the product. And although there has been a recent shift towards media materials (video tutorials), documentation is important.
We went from wiki to gitlab to structured and synchronized documentation for two languages in the form of markdown files published in the github repository. And so we started the transition to a bunch of github + Weblate + readTheDocs. Since there are few articles about this on Habré - below about our mistakes, difficulties and experience in setting up translation of an open-source project.
wiki ? . - . — . — .
markdown — wiki docs ru en. . - jira — , . , .
:
- ;
- , git markdown — ;
- , — ;
- ;
- .
, http://readthedocs.org/ — . Python ( node.js) " " . : — sphinx-doc.org. , readthedocs , .
, markdown – , , . reStructuredText.
, . :
Godot Engine:
. , , , , .
markdown reStructuredText. – readthedocs.
iondv/docs-l10n git submodule add https://github.com/iondv/docs-ru. . translation, master . Reathedocs master .
sphinx. . .
latex_elements , utf8, readthedocs .
latex_elements = {
'preamble': '\\usepackage[utf8]{inputenc}',
'babel': '\\usepackage[russian]{babel}',
'cmappkg': '\\usepackage{cmap}',
'fontenc': '\\usepackage[T1,T2A]{fontenc}',
'utf8extra':'\\DeclareUnicodeCharacter{00A0}{\\nobreakspace}',
}
gettext_compact=True, False – Weblate . True – , . , Weblate .
docs-ru, docs-l10n , .
translation.
. , () , Weblate .
(gettext_compact=False), , . – . -, – . , .
. Ubuntu, CentOs . docker service-net, docker network create service-net
-, Weblate – Redis PostgreSql ( )
docker run --name redis -v redis-data:/data \
--expose 6379 --net service-net \
--restart unless-stopped -d \
redis:4-alpine redis-server --appendonly yes
docker run --name postgres -v postgres-data:/var/lib/postgresql/data \
--expose 5432 \
--env "POSTGRES_PASSWORD=123" \
--env "POSTGRES_USER=iondv" \
--env "POSTGRES_DATABASE=weblate" \
--env "POSTGRES_DB=weblate" \
--env "POSTGRES_HOST=postgres" \
--env "POSTGRES_PORT=5432" \
--net service-net --restart unless-stopped -d \
postgres:11-alpine
Weblate . , , github . .
docker run --name weblate \
-v weblate-data:/app/data \
--expose 8080 \
--env "DEBUG=True" \
--env "POSTGRES_PASSWORD=123" \
--env "POSTGRES_USER=iondv" \
--env "POSTGRES_DATABASE=weblate" \
--env "POSTGRES_DB=weblate" \
--env "POSTGRES_HOST=postgres" \
--env "POSTGRES_PORT=5432" \
--env "REDIS_HOST=redis" \
--env "REDIS_PORT=6379" \
--env "WEBLATE_EMAIL_HOST=smtp.yandex.ru" \
--env "WEBLATE_EMAIL_PORT=465" \
--env "WEBLATE_EMAIL_USE_TLS=True" \
--env "WEBLATE_EMAIL_HOST_USER=weblate@YOUR_HOST.com" \
--env "WEBLATE_EMAIL_HOST_PASSWORD=123" \
--env "WEBLATE_SERVER_EMAIL=weblate@ YOUR_HOST.com" \
--env "WEBLATE_DEFAULT_FROM_EMAIL=weblate@ YOUR_HOST.com" \
--env "WEBLATE_ADMIN_PASSWORD=123" \
--env "WEBLATE_ADMIN_NAME=IONDV Weblate Admin" \
--env "WEBLATE_ADMIN_EMAIL=weblate@YOUR_HOST.com" \
--env "WEBLATE_DEBUG=false" \
--env "WEBLATE_LOGLEVEL=DEBUG" \
--env "WEBLATE_SITE_TITLE=IONDV.Doc translation" \
--env "WEBLATE_ALLOWED_HOSTS=weblate.YOUR_HOST.com" \
--env "WEBLATE_REGISTRATION_OPEN=1" \
--env "WEBLATE_REQUIRE_LOGIN=0" \
--env "WEBLATE_TIME_ZONE=Asia/Vladivostok" \
--env "TZ=Asia/Vladivostok" \
--net service-net --restart unless-stopped -d \
weblate/weblate:3.11.2-1
, Weblate 3.10 – , – . 3.11.2-1.
Weblate ssl – nginx, .
/etc/conf.d/weblate.conf
server {
listen 80;
server_name weblate.YOURHOST.ru;
return 301 https://weblate.YOURHOST.ru $request_uri;
}
server {
listen 443;
server_name weblate.YOURHOST.ru;
ssl_stapling on;
resolver 8.8.8.8 valid=300s;
ssl_certificate /etc/nginx/cert/YOURHOST.crt;
ssl_certificate_key /etc/nginx/cert/YOURHOST.key;
ssl_dhparam /etc/nginx/cert/dhparam.pem;
ssl_session_timeout 10m;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers kEECDH+AES128:kEECDH:kEDH:-3DES:kRSA+AES128:kEDH+3DES:DES-CBC3-SHA:!RC4:!aNULL:!eNULL:!MD5:!EXPORT:!LOW:!SEED:!CAMELLIA:!IDEA:!PSK:!SRP:!SSLv2;
ssl_prefer_server_ciphers on;
add_header Strict-Transport-Security "max-age=31536000;";
add_header Content-Security-Policy-Report-Only "default-src https:; script-src https: 'unsafe-eval' 'unsafe-inline'; style-src https: 'unsafe-inline'; img-src https: data:; font-src https: data:; report-uri /csp-report";
location / {
proxy_pass http://weblate:8080;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-NginX-Proxy true;
proxy_ssl_session_reuse off;
proxy_set_header Host $http_host;
proxy_redirect off;
}
access_log /var/log/nginx/weblate.access.log;
error_log /var/log/nginx/weblate.error.log error;
}
github, nginx.
nginx
docker run --name nginx_proxy \
-v /etc/nginx.conf:/etc/nginx/nginx.conf:ro -v /etc/conf.d:/etc/nginx/conf.d:ro \
-v /etc/nginx/cert:/etc/nginx/cert:ro -v /var/log/nginx:/var/log/nginx \
-p "80:80" -p "443:443" --net service-net \
--env "TZ=Asia/Vladivostok" \
--restart unless-stopped -d \
nginx
sphinx
, cron, . sphinx .
Dockerfile
FROM python:3-alpine
RUN apk add --update make && pip install sphinx sphinx_rtd_theme sphinx-intl
WORKDIR /docs
VOLUME ["/docs"]
CMD []
Dockerfile docker image build -t sphinx:latest .
/workspace/docs-l10n — docs-ru , workspace .
githib.com . https://github.com/settings/tokens. Weblate.
() , , sphinx-. gitUser gitToken .
#!/bin/bash
gitToken="111111111111111111111111111111111"
gitUser="user"
curDir=`pwd`
cd ${0%/*} && scriptDir=`pwd` && cd $curDir
l10nDir=$scriptDir/iondv-docs-l10n
docsDir=$l10nDir/docs-ru
if [ -d $l10nDir ]; then
cd $l10nDir
git branch | grep "^* translation"
if [ $? -ne 0 ]; then git checkout translation; git branch | grep "^* translation"; if [ $? -ne 0 ]; then echo " translation "; exit; fi
fi
resPull=`git pull`
resPullSatus=$?
cd $curDir
echo -n " l10n: " && echo $resPull | grep "Already up to date"
if [ $? -eq 0 ]; then echo " l10n"; fi
else
git clone https://$gitUser:$gitToken@github.com/iondv/docs-l10n -b translation $l10nDir
cd $l10nDir
git branch | grep "^* translation"
if [ $? -ne 0 ]; then echo " translation "; exit; fi
fi
if [ -d $docsDir/.git ]; then
cd $docsDir
resPull=`git pull`
resPullSatus=$?
cd $curDir
echo -n " docs-ru: " && echo $resPull | grep "Already up to date"
if [ $? -eq 0 ]; then echo " . "; exit; fi
else
git clone https://$gitUser:$gitToken@github.com/iondv/docs-ru $docsDir
fi
docker run -it --rm -v $l10nDir:/docs sphinx sphinx-build -b gettext /docs/docs-ru /docs/gettext
if [ $? -ne 0 ]; then echo " gettex"; exit 1; fi
docker run -it --rm -v $l10nDir:/docs sphinx sphinx-intl update -p /docs/gettext -l en
if [ $? -ne 0 ]; then echo " "; exit 1; fi
docker run -it --rm -v $l10nDir:/docs sphinx chmod -R ugo+r /docs/gettext /docs/locales
curDate=`date +"%Y%m%d-%H-%M"`
cd $l10nDir
gitStatus=`git status | grep "nothing to commit, working tree clean"`
if [ $? -eq 0 ]; then
echo " "
exit 0
else
echo " "
git add .
git commit -a -m "$curDate autoupdate sphinx locales"
git push
fi
Weblate
, . () – [] (https://weblate.iondv.com/projects/docs/) – .
– , .
– gettex. , , .
. , , .
URL – , . https://USER:123@github.com/iondv/docs-l10n, USER – , 123 .
« ». gettex – .. sphinx pot.
, . , index docs.
, , – .. . weblate://docs/index.
.
( , ). , – .. https://github.com/iondv/docs-l10n . , , «».
, translation. master. , gettex – sphinx- inondv/docs-ru. locales/en/LC_MESSAGES .
readthedocs.org
readthedocs.io .
iondv/docs-l10n. url NAME.reathedocs.io. «Edit advanced project options» — , . , – .
Build – . iondv/docs-l10n, iondv/docs-ru.
“View docs”, , translate master.
. , «iondv-ru» iondv/docs-ru. «Edit advanced project options» «Russian». , , «iondv» «Admin» «Translations» «iondv-ru»
, :
:
- , ;
- Weblate;
- iondv.framework readthedocs, ;
- , ;
- , ;
- .
- weblate ( ).
. , . weblate. – ERR_MSG=' ', ERR_ MSG="Server\'s up and running.'. , GNU gettext, .
– .
– facebook LinkedIn.