Get best of the week

Organisation von Dokumentation und Übersetzung, zum Beispiel iondv. Rahmen


Wie bei vielen Teams, die große Produkte entwickeln , bestand die Aufgabe bei der Entwicklung eines Open-Source-Frameworks fĂŒr die visuelle Erstellung von iondv.framework- Webanwendungen darin, die Funktionen des Systems zu dokumentieren. Zuerst fĂŒr Sie und neue Mitarbeiter. Dann fĂŒr Benutzer. Derzeit ist die Dokumentation ein wichtiges Mittel zur Werbung fĂŒr das Produkt. Und obwohl es in letzter Zeit eine Verlagerung hin zu Medienmaterialien (Video-Tutorials) gegeben hat, ist die Dokumentation wichtig.


Wir gingen vom Wiki ĂŒber Gitlab zur strukturierten und synchronisierten Dokumentation in zwei Sprachen in Form von Markdown-Dateien, die im Github-Repository veröffentlicht wurden. Also haben wir den Übergang zum Bundle github + Weblate + readTheDocs begonnen. Da es auf dem HabrĂ© nur wenige Artikel dazu gibt - unten ĂŒber unsere Fehler, Schwierigkeiten und Erfahrungen bei der Erstellung der Übersetzung eines Open-Source-Projekts.



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.

More articles:


All Articles