Sphinx logo

目次

前のトピックへ

HTMLテーマのサポート

次のトピックへ

Sphinx拡張

このページ

テンプレート

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の組み込みのテーマから使用されています。 tempates_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 はマスタードキュメントへのリンクを含むリストアイテムを含みます。 relbarimtes はデフォルトでは空のブロックです。もしもこれらを上書きして、バーの中に追加のリンクを含める場合には、リストアイテムの末尾には reldelim1 を付けるようにしてください。
document
ドキュメントのコンテンツそのものです。これはそれぞれのコンテンツが page.html などのサブのテンプレートで整形して置かれる “body” ブロックを含みます。
sidebar1 / sidebar2

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

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

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

sidebarlogo
サイドバーの中にロゴを置くための位置を示すブロックです。もしもサイドバーの最上段に何かコンテンツを置きたい場合には、このブロックをオーバーライドします。
sidebartoc
サイドバー内部の目次です。
sidebarrel
サイドバー内の関連リンク(前後のトピックへのリンク)です。
sidebarsourcelink
サイドバー内の “ソースコードを表示” へのリンクです。通常は設定の html_show_sourcelink が有効になっている時にだけ表示されます。
sidebarsearch
サイドバー内の検索ボックスです。いくつかのコンテンツをサイドバーの下部に追加したい場合には、このブロックをオーバーライドします。
footer
フッターのブロックです。フッターをカスタマイズしたり、フッターの前後にマークアップを追加したりしたい時には、このブロックをオーバーライドします。

設定値

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

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

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

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

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

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

{% set script_files = script_files + [pathto(“_static/myscript.js”, 1)] %}

ヘルパー関数

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

pathto(ドキュメント)
SphinxドキュメントへのURLを返します。これは組み込みのドキュメントを参照する場合に使用します。
pathto(ファイル, 1)
ファイル に対する、生成されたドキュメントのルートからの相対パスによるリンクを返します。静的なファイルを参照するのに使用します。
hasdoc(ドキュメント)
ドキュメント で指定された名前のドキュメントが存在するかどうかチェックします。
レンダリングされたサイドバーを返します。
relbar()
レンダリングリレーションバーを返します。

グローバル変数

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

builder
ビルダーの名前が格納されている変数です。 html, htmlhelp などの値が入ります。
copyright の値が入ります。
docstitle
ドキュメントのタイトルです。 html_title で設定した値が入ります。
embedded
ウェブブラウザではなく、HTMLヘルプや、Qtヘルプフォーマットなどの、専用のビューアーアプリケーション内で使用される組み込みのHTMLの場合にTrueとなります。これがTrueの場合には、サイドバーが含まれなくなります。
favicon
HTMLのfaviconを表す静的パスです。設定されない場合には '' となります。
file_suffix
ビルダーの out_suffix アトリビュートの値です。出力ファイル名に付く拡張子などです。標準のHTMLビルダーの場合には、通常は .html になります。
has_source
もしreSTドキュメントソースがコピーされている場合にTrueになります。 html_copy_source がtrueに設定されるとコピーされます。
last_updated
ビルドされた日時です。
HTMLに貼り付けられるロゴ画像の静的なパスです。指定されていない場合には '' になります。
master_doc
master_doc の値が入ります。 pathto() と一緒に使用します。
next

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

{% if next %}
<a href="{{ next.link|e }}">{{ next.title }}</a>
{% endif %}
pagename
現在のファイルの “ページ名” です。reSTのソースから生成されていたらドキュメント名になります。あるいは出力ディレクトリからの相対パス名から拡張子を抜いた名前 ([ディレクトリ/]拡張子なしのファイル名) となる、階層名付きの名前になります。
parents
ナビゲーションのための、親のドキュメントのリストです。それぞれの要素は next と同じような構造体になっています。
prev
「前のトピック」にあたるページの情報です。 :data`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
ドキュメントのメタデータです。 metadata を参照してください。
sourcename
現在のドキュメントのコピーされたソースファイル名です。 html_copy_source の値がtrueでない場合には 空になります。
toc
現在のページのためのローカルの目次です。HTMLのリストとしてレンダリングされています。
toctree
現在のページを含むグローバルな目次ツリーを生成する、呼び出し可能オブジェクトです。HTMLリストとしてレンダリングされています。もしオプションのキーワード引数の collapse がtrueの場合には、現在のページの祖先にあたる目次のエントリー以外は折りたたまれます。