Get best of the week

Organisation de la documentation et de la traduction, par exemple, iondv. cadre


Comme de nombreuses équipes développant de gros produits, lors du développement d'un framework open source pour la création visuelle d'applications web iondv.framework , la tâche consistait à documenter les capacités du système. Tout d'abord pour vous et les nouveaux employés. Ensuite pour les utilisateurs. Et à l'heure actuelle, la documentation est un moyen important de promouvoir le produit. Et bien qu'il y ait eu récemment un virage vers les supports médiatiques (didacticiels vidéo), la documentation est importante.


Nous sommes passés de wiki à gitlab à une documentation structurée et synchronisée en deux langues sous forme de fichiers de démarques publiés dans le référentiel github. Nous avons donc commencé la transition vers le bundle github + Weblate + readTheDocs. Puisqu'il y a peu d'articles à ce sujet sur Habré - ci-dessous sur nos erreurs, nos difficultés et notre expérience dans la mise en place de la traduction d'un projet open-source.



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