👠 🧘🏾 🛰️ उदाहरण के लिए, प्रलेखन और अनुवाद का संगठन, आयनडव। ढांचा 🥤 ☸️ 🖖🏻

आयनडव.फ्रेमवर्क वेब अनुप्रयोगों के दृश्य निर्माण के लिए एक खुला स्रोत ढांचा विकसित करते समय बड़े उत्पादों को विकसित करने वाली कई टीमों की तरह , कार्य प्रणाली की क्षमताओं का दस्तावेजीकरण करना था। पहले अपने लिए और नए कर्मचारियों के लिए। फिर उपयोगकर्ताओं के लिए। और वर्तमान में, प्रलेखन उत्पाद को बढ़ावा देने का एक महत्वपूर्ण साधन है। और यद्यपि मीडिया सामग्री (वीडियो ट्यूटोरियल) की ओर हाल ही में बदलाव हुआ है, प्रलेखन महत्वपूर्ण है।

हम गीथ रिपब्लिक में प्रकाशित मार्कडाउन फ़ाइलों के रूप में दो भाषाओं के लिए संरचित और सिंक्रनाइज़ प्रलेखन के लिए विकी से गिटलैब तक गए। इसलिए हमने github + Weblate + readTheDocs बंडल में संक्रमण शुरू किया। चूँकि Habré पर इसके बारे में कुछ लेख हैं - नीचे एक ओपन-सोर्स प्रोजेक्ट के अनुवाद को स्थापित करने में हमारी गलतियों, कठिनाइयों और अनुभव के बारे में।

wiki ? . - . — . — .

markdown — wiki docs ru en. . - jira — , . , .

;
, git markdown — ;
, — ;
;
.

, http://readthedocs.org/ — . Python ( node.js) " " . : — sphinx-doc.org. , readthedocs , .

, markdown – , , . reStructuredText.

, . :

https://github.com/iondv/docs-ru ;
https://github.com/iondv/docs-l10n — weblate ;
sphinx;
weblate https://weblate.iondv.com ;
readthedocs https://iondv.readthedocs.io/ ( — ).
, .

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