Date: 2009-10-11
Tags: zope, python

Zope2 ドキュメントを Sphinx でビルドする手順

先週の日曜日に http://docs.zope.jp/ を公開しましたが、このサイトは http://docs.zope.org/ のソースコードを取得して翻訳したものを Sphinx でビルドして作っています。 Sphinx は reStructuredText で書かれたドキュメントをビルドして html や pdf, chm などを出力する仕組みで、詳しくは渋川さんが翻訳してくれた Sphinxドキュメントの日本語訳渋日記: Pythonって何?という人のためのSphinxチュートリアル を参照してください。

以下、 http://docs.zope.jp/zope2/ を出力するための手順です。

docs.zope.jp ビルド

$ cd zope2docs
$ python bootstrap.py
$ bin/buildout -v
$ bin/sphinx-build . html

上記の手順で、既存のPython環境に手を加えずにSphinxのインストールを行い、htmlのビルドが出来ました。出来上がったhtmlファイル群はhtmlというディレクトリ以下に作成されています。上記の例ではWindowsでも動作するように書きましたが、チェックアウトするとMakefileも付いてくるので、 make html としてもOKです。

また、英語版のビルドを行う場合は、一番最初のチェックアウトするソースコードの場所を http://svn.zope.org/repos/main/zope2docs/trunk/ にすれば良いはずです(2009/10/10時点)。

Sphinxのテンプレートカスタマイズ

docs.zope.jp では、ちょっとだけテンプレートをカスタマイズしていて、本家と違うところがあります。ファイル的には layout.html を追加していて、Sphinxで生成したhtmlファイルにGoogleAnalyticsのトラッカーを埋め込んだり、問い合わせ先についてのリンクを設置したりしています。こんな感じです:

{% extends "!layout.html" %}

{%- block rootrellink %}
<li><a target="_blank" href="http://docs.zope.org/zope2/" title="English(Original)">English(Original)</a></li>
{{ reldelim2 }}
<li><a target="_blank" href="http://zope.jp/" title="日本Zopeユーザー会 - JZUG">JZUG</a></li>
{{ reldelim2 }}
{{ super() }}
{%- endblock %}


{%- block sidebarsearch %}
{{ super() }}
<h3>お問い合わせ</h3>
<div>
  <p>
    日本語訳についてのご意見などは
    <a target="_blank" href="http://zope.jp/contact-info">zope.jp の連絡フォーム</a>
    からお願いします。
  </p>
</div>
{%- endblock %}

{% block footer %}
{{ super() }}
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-xxxxxxx-1");
pageTracker._trackPageview();
} catch(err) {}</script>
{% endblock %}

GoogleAnalyticsの埋め込み部分については Adding Google Analytics to Sphinx Docs | Surfing in Kansas を参考にし、その他のカスタマイズについては テンプレート - Sphinx v1.0 (hg) documentation を読みながら作成しています。