Date: 2014-01-26
Tags: sphinx, translation, drone.io, aws, s3, boto, route53, iam

Sphinx翻訳ドキュメントのビルドと公開の自動化(transifex, drone.io, S3)

Sphinx+翻訳 Hack-a-thon 2014.1 に参加しています。その成果です。

以前から @shkumagai が取り組んでいたdocutilsの翻訳をTransifexに乗せてhtmlページ生成まで自動化しました。

全体の構成

  • 自動ビルドは drone.io で行います

  • docutilsのソースは http://svn.code.sf.net/p/docutils/code/trunk にあり、読み取りのみ可能です

  • 自動化のための追加のファイルをbitbucketに置きます

  • 翻訳は Transifex で行います

  • Web公開はAWSのS3で行い、DNS登録はRoute53で行います。

AWS

  • AWSアカウントを開設(既存アカウントでやると支払いが混ざるので別アカウントで)

  • S3でbucketを作る: docutils.sphinx-users.jp

  • bucketのStatic Website HostingをEnableにする: Index Document: index.html

  • IAMでboto接続用アカウントを作成し、Access Keyを生成しておく: sphinxjp-web-bucket

  • IAMのsphinxjp-web-bucketアカウントのポリシーでS3への書き込み権限をあたえる:

    {
      "Statement": [
        {
          "Sid": "Stmt1210121092112",
          "Action": [
            "s3:DeleteObject",
            "s3:GetObject",
            "s3:GetObjectAcl",
            "s3:ListBucket",
            "s3:PutObject",
            "s3:PutObjectAcl"
          ],
          "Effect": "Allow",
          "Resource": [
            "arn:aws:s3:::docutils.sphinx-users.jp",
            "arn:aws:s3:::docutils.sphinx-users.jp/*"
          ]
        }
      ]
    }
    
  • Route53でdocutils.sphinx-users.jpをDNS登録する:

    Name

    docutils.sphinx-users.jp

    Type

    A - IPv4 address

    Alias

    Yes

    Alias Target

    S3 Website Endpoint の docutils.sphinx-users.jp

Transifex

Bitbucket

docutilsはSphinxドキュメントではないのでconf.pyや追加のindexを用意します。

  • https://bitbucket.org/sphinxjp/docutils-translation リポジトリを作り、以下のファイルを追加:

    • .tx/config: potやpoファイルとtransifex上のリソースとの対応付けファイル

    • index.txt: docutilsの各ドキュメントへのリンクを書いたSphinx用トップページ

    • conf.py: 必要最小限のSphinx設定、gettext設定を含む

    • droneio.sh: 翻訳を適用してドキュメントをビルドする手順:

      ##################################
      # get docutils source
      svn export --force http://svn.code.sf.net/p/docutils/code/trunk .
      
      ################################
      # setup sphinx and others
      pip install sphinx boto_rsync babel sphinx-intl transifex-client
      
      ################################
      # setup transifex setting files
      sphinx-intl create-transifexrc        #create ~/.transifexrc
      
      ###########################
      # make translated document
      tx pull --all                         #pull po files from transifex
      sphinx-intl build                     #compile po -> mo
      sphinx-build -b html -d _build/doctrees -Dlanguage=ja . _build/html
      
      ##################################
      # deploy to s3
      boto-rsync --delete -g public-read _build/html s3://docutils.sphinx-users.jp/
      

Drone.io

https://drone.io/bitbucket.org/sphinxjp/docutils-translation/admin

  • アカウントを開設する(既存があれば利用)

  • New Project で bitbucket.org/sphinxjp/docutils-translation を選択して作成

  • Environment Variables にsphinx-intlとAWSの鍵などを設定:

    PIP_USE_WHEEL=true
    SPHINXINTL_TRANSIFEX_USERNAME=<YOUR-TRANSIFEX-ID>
    SPHINXINTL_TRANSIFEX_PASSWORD=<YOUR-TRANSIFEX-PW>
    SPHINXINTL_LOCALE_DIRS=locale
    AWS_ACCESS_KEY_ID=<YOUR-AWS-ACCESS-KEY>
    AWS_SECRET_ACCESS_KEY=<YOUR-AWS-SECRET-ACCESS-KEY>
    

    環境変数の内容は管理権限のあるひとしか見れないので鍵設定に便利。

  • Commandsに sh -x droneio.sh

droneio.shの内容をCommandsに書いておいてもいいですが、差分管理出来なくなるので、リポジトリに入れています。

まとめ

docutilsドキュメントの翻訳を http://docutils.sphinx-users.jp/ で見れるようになりました。 @shkumagai ++

でもまだまだ訳されていない部分が多いので、 https://www.transifex.com/projects/p/docutils/language/ja/ に参加して、みんなで翻訳しましょう!