テンプレート

Sphinx uses the Jinja templating engine for its HTML templates. Jinja is a text-based engine, inspired by Django templates, so anyone having used Django will already be familiar with it. It also has excellent documentation for those who need to make themselves familiar with it.

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

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

  • 読者が使用したいテンプレートエンジンを呼び出すような TemplateBridge クラスのサブクラスを書いて、それが呼ばれるように template_bridge 設定値に設定します。

  • StandaloneHTMLBuilder を継承して カスタムビルダーを書いて 好きなテンプレートエンジンを呼ぶようにします。

  • You can use the PickleHTMLBuilder that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application.

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="https://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

This block contains the relation bar, the list of related links (the parent documents on the left, and the links to index, modules etc. on the right). relbar1 appears before the document, relbar2 after the document. By default, both blocks are filled; to show the relbar only before the document, you would override relbar2 like this:

{% block relbar2 %}{% endblock %}
rootrellink, relbaritems

Inside the relbar there are three sections: The rootrellink, the links from the documentation and the custom relbaritems. The rootrellink is a block that by default contains a list item pointing to the root document by default, the relbaritems is an empty block. If you override them to add extra links into the bar make sure that they are list items and end with the reldelim1.

document

ドキュメントのコンテンツそのものです。これはそれぞれのコンテンツが page.html などのサブのテンプレートで整形して置かれる "body" ブロックを含みます。

注釈

In order for the built-in JavaScript search to show a page preview on the results page, the document or body content should be wrapped in an HTML element containing the role="main" attribute. For example:

<div role="main">
  {% block document %}{% endblock %}
</div>
sidebar1, sidebar2

A possible location for a sidebar. sidebar1 appears before the document and is empty by default, sidebar2 after the document and contains the default sidebar. If you want to swap the sidebar location override this and call the sidebar helper:

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

(The sidebar2 location for the sidebar is needed by the sphinxdoc.css stylesheet, for example.)

sidebarlogo

サイドバーの中にロゴを置くための位置を示すブロックです。もしもサイドバーの最上段に何かコンテンツを置きたい場合には、このブロックをオーバーライドします。

footer

footerのdivのために使われるブロックです。もし、独自のfooterや、前後にマークアップを追加したい場合、これを上書きしてください。

以下の４つのブロックは 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"] %}

バージョン 1.8.0 で非推奨: 代わりに .Sphinx.add_js_file() を使用してください。

ヘルパー関数

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

pathto(document)

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

pathto(file, 1)

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

hasdoc(document)

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

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

relbar()

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

warning(message)

警告メッセージを発生させます。

グローバル変数

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

builder

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

copyright の値が入ります。

docstitle

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

embedded

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

favicon_url

The relative path to the HTML favicon image from the current document, or URL to the favicon, or ''.

Added in version 4.0.

file_suffix

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

has_source

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

language

language の値。

last_updated

ビルドされた日時です。

logo_url

The relative path to the HTML logo image from the current document, or URL to the logo, or ''.

Added in version 4.0.

master_doc

Same as root_doc.

バージョン 4.0 で変更: Renamed to root_doc.

root_doc

The value of root_doc, for usage with pathto().

バージョン 4.0 で変更: Renamed from master_doc.

pagename

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

project

project の値になります。

release

release の値になります。

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

shorttitle

html_short_title の値になります。

show_source

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

sphinx_version

The version of Sphinx used to build represented as a string for example "3.5.1".

sphinx_version_tuple

The version of Sphinx used to build represented as a tuple of five elements. For Sphinx version 3.5.1 beta 3 this would be (3, 5, 1, 'beta', 3). The fourth element can be one of: alpha, beta, rc, final. final always has 0 as the last element.

Added in version 4.2.

docutils_version_info

The version of Docutils used to build represented as a tuple of five elements. For Docutils version 0.16.1 beta 2 this would be (0, 16, 1, 'beta', 2). The fourth element can be one of: alpha, beta, candidate, final. final always has 0 as the last element.

Added in version 5.0.2.

styles

A list of the names of the main stylesheets as given by the theme or html_style.

Added in version 5.1.

title

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

use_opensearch

html_use_opensearch の値が入ります。

version

version の値が入ります。

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

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

body

HTML形式のページのコンテンツ文字列で、HTMLビルダーが生成したテーマが適用される前のものです。

display_toc

tocが2つ以上のエントリーを含む場合に True になる、ブール型の値になります。

meta

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

metatags

このページのHTMLの meta タグ文字列です。

next

The next document for the navigation. This variable is either false or has two attributes link and title. The title contains HTML markup. For example, to generate a link to the next page, you can use this snippet:

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

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

parents

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

prev

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

sourcename

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

toc

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

toctree

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

collapse

If true, all TOC entries that are not ancestors of the current page are collapsed. True by default.

maxdepth

The maximum depth of the tree. Set it to -1 to allow unlimited depth. Defaults to the max depth selected in the toctree directive.

titles_only

If true, put only top-level document titles in the tree. False by default.

includehidden

If true, the ToC tree will also contain hidden entries. False by default.