テンプレート

SphinxはHTMLのテンプレートとして Jinja テンプレートエンジンを利用しています。Jinjaは、Djangoのテンプレートにインスパイアされた、テキストベースのテンプレートエンジンです。Djangoを触ったことがある人ならば、すぐに慣れるでしょう。つまり、Djangoテンプレート用に書かれた、既存のすばらしいドキュメントは、Jinjaを学ぼうとしている人にも役に立つということを意味しています。

HTMLを生成するのにSphinxのテンプレートを使用する必要があるのか?

必要はありません。いくつか別の選択肢を選ぶことができます。

  • 読者が使用したいテンプレートエンジンを呼び出すような TemplateBridge クラスのサブクラスを書いて、それが呼ばれるように template_bridge 設定値に設定します。
  • StandaloneHTMLBuilder を継承して カスタムビルダーを書いて 好きなテンプレートエンジンを呼ぶようにします。
  • ページの内容を含むpickleファイルを生成する PickleHTMLBuilder を使用して、自分でカスタムしたツールや、ウェブアプリケーション内などで後処理を行います。

Jinja/Sphinxテンプレートの基礎

Sphinxのデフォルトのテンプレート言語はJinjaです。これはDjango/Smartyにインスパイアされて作成されたもので、理解しやすくなっています。Jinjaにおける最も重要なコンセプトは テンプレート継承 です。これは、テンプレートの特定のブロックのみをオーバーライドして、変更箇所を最小限にしたカスタマイズを可能にします。

ドキュメントの出力をカスタマイズするには、Sphinxのquickstartコマンドが生成したテンプレートのディレクトリに、オリジナルファイル名と同じ名前のテンプレートを追加して、すべてのテンプレート(レイアウトのテンプレートと子供のテンプレート)をオーバーライドするという方法があります。

Sphinxはまず最初に、 templates_path で設定されたフォルダのテンプレートを見に行きます。そして、そこで見つからなければ、選択しているテーマのテンプレートを探しに行きます。

テンプレートは、テンプレートが評価される時に値が置き換えられる 変数 と、テンプレートのロジックを制御する タグ, テンプレートの継承に使用される ブロック の3種類の要素を含みます。

Sphinxの basic テーマでは2つのブロックを持つ基本となるテンプレートを提供しています。このブロックはデータで埋められます。これらのファイルはSphinxのインストールディレクトリの中の themes/basic サブディレクトリ内に置かれています。このテーマはすべてのSphinxの組み込みのテーマから使用されています。 templates_path に入っている同名のテンプレートは、選択されたテーマのテンプレートよりも優先的に使用されるので、既存のテーマのテンプレートをオーバーライドします。

例えば、新しいリンクをテンプレートの関連リンクを含む領域に追加する場合には、 layout.html と呼ばれる新しいテンプレートを作成して、以下の内容を書き込みます:

{% extends "!layout.html" %}
{% block rootrellink %}
    <li><a href="http://project.invalid/">Project Homepage</a> &raquo;</li>
    {{ super() }}
{% endblock %}

オーバーライドされるテンプレート名の前にエクスクラメーションマーク(!)を付けることで、SphinxはベースとなるHTMLテーマのテンプレートをロードします。

重要: もしブロックをオーバーライドするときは、拡張される側の内容を表示したくない場合以外の場合には、 {{ super() }} をコールすると、拡張される方のテンプレートのブロックの内容をレンダリングできます。

組み込みテンプレートの働き

組み込みの basic テーマはすべての組み込みSphinxテーマの骨組みとなるテンプレートを提供しています。このうち、以下の要素オーバーライドしたり、使用したりできます。

ブロック

layout.html テンプレートの中には、次のようなブロックが定義されています。

doctype
出力フォーマットのドキュメントのタイプです。デフォルトでは、SphinxとDocutilsが生成する結果にもっとも近いXHTML 1.0 Transitionalになっています。HTML 5やその他のXHTMLと互換性のあるdoctype以外のタイプには変更しない方がいいでしょう。
linktags
このブロックは、テンプレートのheadセクションに <link> タグをいくつか追加するものです。
extrahead
このブロックはデフォルトでは空です。このブロックを使うと、追加の内容を生成されたHTMLファイルの <head> タグに追加の情報を出力できます。JavaScriptや追加のCSSファイルへの参照を追加する場合にはこのブロックを使用します。
relbar1 / relbar2

このブロックは、 リレーションバー を含みます。リレーションバーは左側に親ドキュメントを、右側に索引、モジュール索引などを含みます。 relbar1 はドキュメントの前に、 relbar2 はドキュメントの後に表示されます。デフォルトではそれぞれのブロックの内容が表示されます。もしも、ドキュメントの前だけ表示したい場合には、以下のように relbar2 をオーバーライドします:

{% block relbar2 %}{% endblock %}
rootrellink / relbaritems
リレーションバーは3つのセクションで構成されています。 rootrellink と、ドキュメントからのリンク, カスタムの relbaritems の3つです。デフォルトでは rootrellink はマスタードキュメントへのリンクを含むリストアイテムを含みます。 relbaritems はデフォルトでは空のブロックです。もしもこれらを上書きして、バーの中に追加のリンクを含める場合には、リストアイテムの末尾には reldelim1 を付けるようにしてください。
document
ドキュメントのコンテンツそのものです。これはそれぞれのコンテンツが page.html などのサブのテンプレートで整形して置かれる “body” ブロックを含みます。
sidebar1 / sidebar2

サイドバーが入る可能性のある場所を示すブロックです。 sidebar1 はドキュメントの前にあり、デフォルトでは空です。 sidebar2 はドキュメントの後ろにあり、デフォルトのサイドバーを含んでいます。もし、サイドバーの位置を入れ替えたい場合には以下のようにオーバーライドして、 sidebar ヘルパーを呼び出します:

{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}

サイドバーが置かれる sidebar2 の位置も sphinxdoc.css といったスタイルシートから必要になります。

sidebarlogo
サイドバーの中にロゴを置くための位置を示すブロックです。もしもサイドバーの最上段に何かコンテンツを置きたい場合には、このブロックをオーバーライドします。
footer
footerのdivのために使われるブロックです。もし、独自のfooterや、前後にマークアップを追加したい場合、これを上書きしてください。

以下の4つのブロックは html_sidebars 設定のカスタムサイドバーのリストに割り当てられないページに のみ 使われています。 html_sidebars を使って含められる、分割されたサイドバーテンプレートの中では撤廃されています。

sidebartoc

サイドバー内部の目次です。

バージョン 1.0 で撤廃.

sidebarrel

サイドバー内の関連リンク(前後のトピックへのリンク)です。

バージョン 1.0 で撤廃.

sidebarsourcelink

サイドバー内の “ソースコードを表示” へのリンクです。通常は設定の html_show_sourcelink が有効になっている時にだけ表示されます。

バージョン 1.0 で撤廃.

sidebarsearch

サイドバー内の検索ボックスです。いくつかのコンテンツをサイドバーの下部に追加したい場合には、このブロックをオーバーライドします。

バージョン 1.0 で撤廃.

設定値

テンプレート内では、 {% set %} タグを利用して、テンプレートのレイアウトに使用される変数をセットできます。

reldelim1

リレーションバーの左側アイテムの区切り文字です。デフォルトは ' &raquo;' です。リレーションバーに含まれるアイテムはすべて、ここで指定した変数の値で区切られます。

reldelim2

リレーションバーの右側のアイテムの区切り文字になります。デフォルトは ' |' です。最後の要素を除くすべてのリレーションバーのアイテムは、ここで指定された変数の値で区切られます。

以下のようにオーバーライドします:

{% extends "!layout.html" %}
{% set reldelim1 = ' &gt;' %}
script_files

以下のように記述すると、追加のスクリプトファイルをここで追加できます:

{% set script_files = script_files + ["_static/myscript.js"] %}
css_files

script_files に似ていますが、CSSファイルのために使われます。

ヘルパー関数

Sphinxはテンプレートで使用できるJinja関数をいくつか提供しています。これを使用すると、リンクを生成したり、構成要素を使用した出力を何度も行ったりできるようになります。

pathto(document)

SphinxドキュメントへのURLを返します。これは組み込みのドキュメントを参照する場合に使用します。

pathto(file, 1)

ファイル に対する、生成されたドキュメントのルートからの相対パスによるリンクを返します。静的なファイルを参照するのに使用します。

hasdoc(document)

ドキュメント で指定された名前のドキュメントが存在するかどうかチェックします。

レンダリングされたサイドバーを返します。

relbar()

レンダリングリレーションバーを返します。

グローバル変数

これらのグローバル変数はすべてのテンプレートで利用可能で、安全に使用できる変数です。ここで説明されているよりも多くの変数がありますが、それらの変数は、実装に根ざした内部変数であったり、将来挙動が変更される予定のものになります。

builder

ビルダーの名前が格納されている変数です。 html, htmlhelp などの値が入ります。

copyright の値が入ります。

docstitle

ドキュメントのタイトル (html_title の値)です。”single-file” ビルダーが使われた場合と None を設定した場合は除きます。

embedded

ウェブブラウザではなく、HTMLヘルプや、Qtヘルプフォーマットなどの、専用のビューアーアプリケーション内で使用される組み込みのHTMLの場合にTrueとなります。これがTrueの場合には、サイドバーが含まれなくなります。

favicon

HTMLのfaviconを表す静的パスです。設定されない場合には '' となります。

file_suffix

ビルダーの out_suffix アトリビュートの値です。出力ファイル名に付く拡張子などです。標準のHTMLビルダーの場合には、通常は .html になります。

has_source

reSTドキュメントソースがコピーされた場合、Trueになります。 (html_copy_sourceTrue に設定されるとコピーされます。)

language

language の値。

last_updated

ビルドされた日時です。

HTMLに貼り付けられるロゴ画像の静的なパスです。指定されていない場合には '' になります。

master_doc

master_doc の値が入ります。 pathto() と一緒に使用します。

next

ナビゲーションで「次のトピック」にあたるドキュメントです。この変数は false か、 linktitle の二つの属性を持つオブジェクトのどちらかになります。タイトルにはHTMLのマークアップが含まれます。例えば、次のページへのリンクを生成するには、以下のようなコードを利用します:

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}
pagename

現在のファイルの “ページ名” です。reSTのソースから生成されていたらドキュメント名になります。あるいは出力ディレクトリからの相対パス名から拡張子を抜いた名前 ([ディレクトリ/]拡張子なしのファイル名) となる、階層名付きの名前になります。

parents

ナビゲーションのための、親のドキュメントのリストです。それぞれの要素は next と同じような構造体になっています。

prev

「前のトピック」にあたるページの情報です。 next と似ています。

project

project の値になります。

release

release の値になります。

リレーションバーの左側(?)、 “次”, “前” のとなりに置かれるリンクのリストです。通常では、索引とモジュール索引へのリンクが含まれています。もしここに何かを追加する場合には、 (ページ名, リンクタイトル, アクセスキー, リンクテキスト) というタプルを追加します。

shorttitle

html_short_title の値になります。

show_source

html_show_sourcelink がtrueの場合に True になります。

sphinx_version

ビルドに使用されたSphinxのバージョンです。

style

メインのスタイルシートの名前です。テーマで設定されたものか、あるいは html_style で設定されている値になります。

title

現在のドキュメントのタイトルです。これは <title> タグで使用されます。

use_opensearch

html_use_opensearch の値が入ります。

version

version の値が入ります。

これらの値に加えて、すべての テーマオプション も利用可能です。テーマオプションには theme_ という文字列が先頭に付きます。ユーザが html_context を通じて設定した値も同じように利用可能です。

ソースファイルから生成されるドキュメント内では、以下のオプションも利用可能です。ただし、モジュール索引などの自動生成されるファイルや、最初からHTMLとして生成されるものについては利用できません。

meta

ドキュメントのメタデータの辞書です。 ファイルに関するメタデータ を参照してください。

sourcename

現在のドキュメントのコピーされたソースファイル名です。 html_copy_source の値が True でない場合には 空になります。自動生成されるファイルでは空文字列です。

toc

現在のページのためのローカルの目次です。HTMLのリストとしてレンダリングされています。

toctree

現在のページを含むグローバルな目次ツリーを生成する、呼び出し可能オブジェクトです。HTMLリストとしてレンダリングされています。次のようなオプションのキーワード引数があります:

  • collapse (デフォルトは True ): Trueの場合には、現在のページの祖先にあたる目次のエントリー以外は折りたたまれます。
  • maxdepth (デフォルトではそのtoctreeディレクティブの最大値): 表示されるツリーの深さの最大値を設定します。 -1 を設定すると深さの制限がなくなります。
  • titles_only (デフォルトは False ): もしTrueが設定されると、ドキュメント内のトップレベルのタイトルだけがツリーに置かれます。
  • includehidden (デフォルトは False ): もしTrueの場合、TOCツリーはhiddenが付けられたエントリーも含みます。
page_source_suffix

レンダリングされたファイルの末尾に追加される文字列です。 source_suffix のlistをサポートしたことから、これはオリジナルのソースファイルへ正しくリンクすることを可能としました。