テンプレート¶

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¶: リレーションバーの左側アイテムの区切り文字です。デフォルトは ' »' です。リレーションバーに含まれるアイテムはすべて、ここで指定した変数の値で区切られます。

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)¶: ドキュメント で指定された名前のドキュメントが存在するかどうかチェックします。

sidebar()¶: レンダリングされたサイドバーを返します。

relbar()¶: レンダリングリレーションバーを返します。

warning(message)¶: 警告メッセージを発生させます。

グローバル変数¶

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

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

copyright¶: 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¶: True if the reStructuredText document sources are copied (if html_copy_source is 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¶
root_doc¶: The value of master_doc or root_doc (aliases), for usage with pathto().

Added in version 4.0: The root_doc template variable.

pagename¶: The "page name" of the current file, i.e. either the document name if the file is generated from a reStructuredText source, or the equivalent hierarchical name relative to the output directory ([directory/]filename_without_extension).

project¶: project の値になります。

release¶: release の値になります。

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

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.