Get best of the week

Organização da documentação e tradução, por exemplo, iondv. estrutura


Como muitas equipes que desenvolvem grandes produtos, ao desenvolver uma estrutura de código aberto para a criação visual de aplicativos da web iondv.framework , a tarefa era documentar os recursos do sistema. Primeiro para você e para os novos funcionários. Então para usuários. E, atualmente, a documentação é um meio importante de promover o produto. E, embora tenha havido uma mudança recente em relação aos materiais de mídia (tutoriais em vídeo), a documentação é importante.


Passamos do wiki ao gitlab para documentação estruturada e sincronizada para dois idiomas na forma de arquivos de remarcação publicados no repositório do github. Então começamos a transição para um monte de github + Weblate + readTheDocs. Como existem poucos artigos sobre isso em Habré - abaixo, sobre nossos erros, dificuldades e experiência na configuração da tradução de um projeto de código aberto.



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