ちゃんと書こうとするといつまでも完成しないような気がしたので、小出しにすることにしました¹。

groongaのリファレンスマニュアルは英語版と日本語版を用意しています。英語版ページには同じ内容の日本語版ページへのリンク、日本語版ページには同じ内容の英語版ページのリンクを用意しています。各ページの上のところにある国旗画像がそのリンクです。以下のように国旗画像で言語を表現しています。

これはSphinxのテーマを使って実現しています。そのやり方について説明します。

ディレクトリ構成

以下のようなディレクトリ構成になっているとします。en/html/以下にはsphinx -Dlanguage=en ...で生成したHTMLがあり、ja/html/以下にはsphinx -Dlanguage=ja ...で生成したHTMLがあります。

.
|-- en
|   `-- html
|       | ... HTMLがたくさん
|       `-- index.html
`-- ja
    `-- html
        | ... HTMLがたくさん
        `-- index.html

この場合、ja/html/index.htmlでは../../en/html/index.htmlへリンクを張ればよいことになります。

設定方法

conf.pyとテーマのlayout.htmlを設定します。

まず、conf.pyで以下のように設定し、-Dlanguage=...で指定した言語をテーマ内で参照できるようにします。

conf.py:

html_context = {"language": language}

次に、テーマ内でlanguageの値を参照してリンクを生成します。groongaのようにページの先頭の方にリンクを入れる場合は以下のようにします。

layout.html:

{% extends "default/layout.html" %}
{% block header %}
  <ul>
  {%- if language != "en" %}
    <li><a href="{{ pathto('../../en/html/', 1) }}{{ pathto(pagename, 0, '.') }}">English</a></li>
  {%- endif %}
  {%- if language != "ja" %}
    <li><a href="{{ pathto('../../ja/html/', 1) }}{{ pathto(pagename, 0, '.') }}">日本語</a></li>
  {%- endif %}
  </ul>
  {{ super() }}
{% endblock %}

pathto(pagename, 0, '.')でトップページから現在のパスへの相対パスを取得している所がポイントです。Sphinxのドキュメントにはこのやり方が書いていませんでしたが、Sphinxのソースを読んでみたらできそうだったのでこうしました。

languageを参照して出力内容を変えるという手法は他のものにも応用できそうですね。

まとめ

groongaのリファレンスマニュアルで実現している、他言語ページへのリンクを自動生成する方法を紹介しました。Sphinxで複数言語用のドキュメントを生成する場合に利用してみてください。

ツイートする

フォローする