Zope2 ドキュメントを Sphinx でビルドする手順¶
先週の日曜日に http://docs.zope.jp/ を公開しましたが、このサイトは http://docs.zope.org/ のソースコードを取得して翻訳したものを Sphinx でビルドして作っています。 Sphinx は reStructuredText で書かれたドキュメントをビルドして html や pdf, chm などを出力する仕組みで、詳しくは渋川さんが翻訳してくれた Sphinxドキュメントの日本語訳 や 渋日記: Pythonって何？という人のためのSphinxチュートリアル を参照してください。
以下、 http://docs.zope.jp/zope2/ を出力するための手順です。
上記の手順で、既存の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 を読みながら作成しています。
