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関数をいくつか提供しています。これを使用すると、リンクを生成したり、構成要素を使用した出力を何度も行ったりできるようになります。
これらのグローバル変数はすべてのテンプレートで利用可能で、安全に使用できる変数です。ここで説明されているよりも多くの変数がありますが、それらの変数は、実装に根ざした内部変数であったり、将来挙動が変更される予定のものになります。
ナビゲーションで「次のトピック」にあたるドキュメントです。この変数はflaseか、 link と title の二つの属性を持つオブジェクトのどちらかになります。タイトルにはHTMLのマークアップが含まれます。例えば、次のページへのリンクを生成するには、以下のようなコードを利用します:
{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}
これらの値に加えて、すべての テーマオプション も利用可能です。テーマオプションには theme_ という文字列が先頭に尽きます。ユーザが html_context を通じて設定した値も同じように利用可能です。
ソースファイルから生成されるドキュメント内では、以下のオプションも利用可能です。ただし、モジュール索引などの自動生成されるファイルや、最初からHTMLとして生成されるものについては利用できません。