SphinxはHTMLのテンプレートとして Jinja テンプレートエンジンを利用しています。Jinjaは、Djangoのテンプレートにインスパイアされた、テキストベースのテンプレートエンジンです。Djangoを触ったことがある人ならば、すぐに慣れるでしょう。つまり、Djangoテンプレート用に書かれた、既存のすばらしいドキュメントは、Jinjaを学ぼうとしている人にも役に立つということを意味しています。
必要はありません。いくつか別の選択肢を選ぶことができます。
Sphinxのデフォルトのテンプレート言語はJinjaです。これはDjango/Smartyにインスパイアされて作成されたもので、理解しやすくなっています。Jinjaにおける最も重要なコンセプトは テンプレート継承 です。これは、テンプレートの特定のブロックのみをオーバーライドして、変更箇所を最小限にしたカスタマイズを可能にします。
ドキュメントの出力をカスタマイズするには、Sphinxのquickstartコマンドが生成したテンプレートのディレクトリに、オリジナルファイル名と同じ名前のテンプレートを追加して、すべてのテンプレート(レイアウトのテンプレートと子供のテンプレート)をオーバーライドするという方法があります。
Sphinxはまず最初に、 templates_path で設定されたフォルダのテンプレートを見に行きます。そして、そこで見つからなければ、選択しているテーマのテンプレートを探しに行きます。
テンプレートは、テンプレートが評価される時に値が置き換えられる 変数 と、テンプレートのロジックを制御する タグ, テンプレートの継承に使用される ブロック の3種類の要素を含みます。
Sphinxの basic テーマでは2つのブロックを持つ基本となるテンプレートを提供しています。このブロックはデータで埋められます。これらのファイルはSphinxのインストールディレクトリの中の themes/basic サブディレクトリ内に置かれています。このテーマはすべてのSphinxの組み込みのテーマから使用されています。 tempates_path に入っている同名のテンプレートは、選択されたテーマのテンプレートよりも優先的に使用されるので、既存のテーマのテンプレートをオーバーライドします。
例えば、新しいリンクをテンプレートの関連リンクを含む領域に追加する場合には、 layout.html と呼ばれる新しいテンプレートを作成して、以下の内容を書き込みます:
{% extends "!layout.html" %}
{% block rootrellink %}
<li><a href="http://project.invalid/">Project Homepage</a> »</li>
{{ super() }}
{% endblock %}
オーバーライドされるテンプレート名の前にエクスクラメーションマーク(!)を付けることで、SphinxはベースとなるHTMLテーマのテンプレートをロードします。
重要: もしブロックをオーバーライドするときは、拡張される側の内容を表示したくない場合以外の場合には、 {{ super() }} をコールすると、拡張される方のテンプレートのブロックの内容をレンダリングすることができます。
組み込みの basic テーマはすべての組み込みSphinxテーマの骨組みとなるテンプレートを提供しています。このうち、以下の要素オーバーライドしたり、使用したりすることができます。
layout.html テンプレートの中には、次のようなブロックが定義されています。
このブロックは、 リレーションバー を含みます。リレーションバーは左側に親ドキュメントを、右側に索引、モジュール索引などを含みます。 relbar1 はドキュメントの前に、 relbar2 はドキュメントの後に表示されます。デフォルトではそれぞれのブロックの内容が表示されます。もしも、ドキュメントの前だけ表示したい場合には、以下のように relbar2 をオーバーライドします:
{% block relbar2 %}{% endblock %}
サイドバーが入る可能性のある場所を示すブロックです。 sidebar1 はドキュメントの前にあり、デフォルトでは空です。 sidebar2 はドキュメントの後ろにあり、デフォルトのサイドバーを含んでいます。もし、サイドバーの位置を入れ替えたい場合には以下のようにオーバーライドして、 sidebar ヘルパーを呼び出します:
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}
サイドバーが置かれる sidebar2 の位置も sphinxdoc.css といったスタイルシートから必要になります。
テンプレート内では、 {% set %} タグを利用して、テンプレートのレイアウトに使用される変数をセットすることができます。
リレーションバーの左側アイテムの区切り文字です。デフォルトは ' »' です。リレーションバーに含まれるアイテムはすべて、ここで指定した変数の値で区切られます。
リレーションバーの右側のアイテムの区切り文字になります。デフォルトは ' |' です。最後の要素を除くすべてのリレーションバーのアイテムは、ここで指定された変数の値で区切られます。
以下のようにオーバーライドします:
{% extends "!layout.html" %}
{% set reldelim1 = ' >' %}
以下のように記述すると、追加のスクリプトファイルをここで追加することができます:
{% set script_files = script_files + [pathto("_static/myscript.js", 1)] %}
Sphinxはテンプレートで使用できるJinja関数をいくつか提供しています。これを使用すると、リンクを生成したり、構成要素を使用した出力を何度も行ったりできるようになります。
SphinxドキュメントへのURLを返します。これは組み込みのドキュメントを参照する場合に使用します。
ファイル に対する、生成されたドキュメントのルートからの相対パスによるリンクを返します。静的なファイルを参照するのに使用します。
ドキュメント で指定された名前のドキュメントが存在するかどうかチェックします。
レンダリングされたサイドバーを返します。
レンダリングリレーションバーを返します。
これらのグローバル変数はすべてのテンプレートで利用可能で、安全に使用できる変数です。ここで説明されているよりも多くの変数がありますが、それらの変数は、実装に根ざした内部変数であったり、将来挙動が変更される予定のものになります。
ビルダーの名前が格納されている変数です。 html, htmlhelp などの値が入ります。
ドキュメントのタイトルです。 html_title で設定した値が入ります。
ウェブブラウザではなく、HTMLヘルプや、Qtヘルプフォーマットなどの、専用のビューアーアプリケーション内で使用される組み込みのHTMLの場合にTrueとなります。これがTrueの場合には、サイドバーが含まれなくなります。
HTMLのfaviconを表す静的パスです。設定されない場合には '' となります。
ビルダーの out_suffix アトリビュートの値です。出力ファイル名に付く拡張子などです。標準のHTMLビルダーの場合には、通常は .html になります。
もしreSTドキュメントソースがコピーされている場合にTrueになります。 html_copy_source がtrueに設定されるとコピーされます。
ビルドされた日時です。
HTMLに貼り付けられるロゴ画像の静的なパスです。指定されていない場合には '' になります。
master_doc の値が入ります。 pathto() と一緒に使用します。
ナビゲーションで「次のトピック」にあたるドキュメントです。この変数は false か、 link と title の二つの属性を持つオブジェクトのどちらかになります。タイトルにはHTMLのマークアップが含まれます。例えば、次のページへのリンクを生成するには、以下のようなコードを利用します:
{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}
現在のファイルの “ページ名” です。reSTのソースから生成されていたらドキュメント名になります。あるいは出力ディレクトリからの相対パス名から拡張子を抜いた名前 ([ディレクトリ/]拡張子なしのファイル名) となる、階層名付きの名前になります。
「前のトピック」にあたるページの情報です。 :data`next` と似ています。
リレーションバーの左側(?)、 “次”, “前” のとなりに置かれるリンクのリストです。通常では、索引とモジュール索引へのリンクが含まれています。もしここに何かを追加する場合には、 (ページ名, リンクタイトル, アクセスキー, リンクテキスト) というタプルを追加します。
html_short_title の値になります。
html_show_sourcelink がtrueの場合にTrueになります。
ビルドに使用されたSphinxのバージョンです。
メインのスタイルシートの名前です。テーマで設定されたものか、あるいは html_style で設定されている値になります。
現在のドキュメントのタイトルです。これは <title> タグで使用されます。
html_use_opensearch の値が入ります。
これらの値に加えて、すべての テーマオプション も利用可能です。テーマオプションには theme_ という文字列が先頭に付きます。ユーザが html_context を通じて設定した値も同じように利用可能です。
ソースファイルから生成されるドキュメント内では、以下のオプションも利用可能です。ただし、モジュール索引などの自動生成されるファイルや、最初からHTMLとして生成されるものについては利用できません。
ドキュメントのメタデータの辞書です。 ファイルに関するメタデータ を参照してください。
現在のドキュメントのコピーされたソースファイル名です。 html_copy_source の値がtrueでない場合には 空になります。
現在のページのためのローカルの目次です。HTMLのリストとしてレンダリングされています。
現在のページを含むグローバルな目次ツリーを生成する、呼び出し可能オブジェクトです。HTMLリストとしてレンダリングされています。次のようなオプションのキーワード引数があります:
- collapse (デフォルトはtrue): trueの場合には、現在のページの祖先にあたる目次のエントリー以外は折りたたまれます。
- maxdepth (デフォルトではそのtoctreeディレクティブの最大値): 表示されるツリーの深さの最大値を設定します。 -1 を設定すると深さの制限がなくなります。
- titles_only (デフォルトはfalse): もしtrueが設定されると、ドキュメント内のトップレベルのタイトルだけがツリーに置かれます。