テンプレート

Sphinx は、HTML テンプレートに Jinja テンプレートエンジンを使用します。Jinja は、Django テンプレートに触発されたテキストベースのエンジンであるため、Django を使用したことがある人ならすでに慣れているでしょう。また、Jinja を理解する必要がある人のために、優れたドキュメントも用意されています。

HTML を生成するために Sphinx のテンプレートを使う必要がありますか？

いいえ。他のいくつかのオプションがあります。

  • 選択したテンプレートエンジンを呼び出す TemplateBridge サブクラスを作成し、それに応じて template_bridge 設定値を設定できます。

  • カスタムビルダーを作成する ことができ、そのカスタムビルダーは StandaloneHTMLBuilder から派生し、選択したテンプレートエンジンを呼び出します。

  • ページの内容を含む pickle ファイルを生成する PickleHTMLBuilder を使用し、カスタムツールを使用して後処理するか、Web アプリケーションで使用することができます。

Jinja/Sphinx テンプレート入門

Sphinx のデフォルトのテンプレート言語は Jinja です。Django/Smarty に影響を受けており、理解しやすい言語です。Jinja で最も重要な概念は、テンプレートの継承 です。これは、テンプレート内の特定のブロックのみを上書きできることを意味し、変更を最小限に抑えながらカスタマイズできます。

ドキュメントの出力をカスタマイズするには、Sphinx のクイックスタートで生成された構造のテンプレートディレクトリに、元のファイル名と同じ名前のファイルを追加することで、すべてのテンプレート（レイアウトテンプレートと子テンプレートの両方）を上書きできます。

Sphinx は、まず templates_path のフォルダーでテンプレートを探し、そこに見つからない場合は、選択したテーマのテンプレートにフォールバックします。

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

Sphinx の basic テーマは、データで埋められるいくつかのブロックを含む基本テンプレートを提供します。これらは、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

出力形式の doctype。デフォルトでは、これは XHTML 1.0 Transitional です。これは、Sphinx と Docutils が生成するものに最も近く、HTML 5 または異なるが互換性のある XHTML doctype に切り替えたい場合を除いて、変更しないことをお勧めします。

linktags

このブロックは、いくつかの <link> タグをテンプレートの head セクションに追加します。

extrahead

このブロックはデフォルトで空であり、生成された HTML ファイルの <head> タグに追加のコンテンツを追加するために使用できます。これは、JavaScript または追加の CSS ファイルへの参照を追加するのに適した場所です。

relbar1、relbar2

このブロックには、関連バー、つまり関連リンクのリスト（左側の親ドキュメント、右側のインデックス、モジュールなどへのリンク）が含まれています。relbar1 はドキュメントの前に表示され、relbar2 はドキュメントの後に表示されます。デフォルトでは、両方のブロックが入力されます。ドキュメントの前にのみ relbar を表示するには、次のように relbar2 を上書きします。

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

relbar 内には、3 つのセクションがあります。rootrellink、ドキュメントからのリンク、カスタムの relbaritems です。rootrellink は、デフォルトでルートドキュメントを指すリスト項目を含むブロックであり、relbaritems は空のブロックです。バーに追加のリンクを追加するためにそれらを上書きする場合は、それらがリスト項目であり、reldelim1 で終わることを確認してください。

document

ドキュメント自体の内容。ここには、個々のコンテンツが page.html のようなサブテンプレートによって配置されるブロック「body」が含まれています。

注意

組み込みの JavaScript 検索で結果ページにページプレビューを表示するには、ドキュメントまたは本文コンテンツが role="main" 属性を含む HTML 要素でラップされている必要があります。たとえば、

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

サイドバーの可能な場所。sidebar1 はドキュメントの前に表示され、デフォルトで空です。sidebar2 はドキュメントの後に表示され、デフォルトのサイドバーが含まれています。サイドバーの場所を交換する場合は、これを上書きして sidebar ヘルパーを呼び出します

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

（たとえば、サイドバーの sidebar2 の場所は、sphinxdoc.css スタイルシートで必要になります。）

sidebarlogo

サイドバー内のロゴの位置。サイドバーの上部にコンテンツを配置する場合は、これを上書きします。

footer

フッター div のブロック。カスタムフッターまたはその前後にマークアップが必要な場合は、これを上書きします。

次の 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"] %}

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

ヘルパー関数

Sphinxは、テンプレート内でヘルパーとしてさまざまなJinja関数を提供します。これらを使用して、リンクを生成したり、複数回使用される要素を出力したりできます。

pathto(document)

SphinxドキュメントへのパスをURLとして返します。これを使用して、ビルドされたドキュメントを参照します。

pathto(file, 1)

生成された出力のルートからの相対ファイル名である*file*へのパスを返します。これを使用して、静的ファイルを参照します。

hasdoc(document)

名前が*document*のドキュメントが存在するかどうかを確認します。

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

relbar()

レンダリングされた関係バーを返します。

warning(message)

警告メッセージを出力します。

グローバル変数

これらのグローバル変数は、すべてのテンプレートで使用でき、安全に使用できます。他にもありますが、ほとんどが実装の詳細であり、将来変更される可能性があります。

builder

ビルダーの名前（例：htmlまたはhtmlhelp）。

copyrightの値。

docstitle

ドキュメントのタイトル（html_titleの値）。ただし、「単一ファイル」ビルダーが使用されている場合は、Noneに設定されます。

embedded

ビルドされたHTMLが、Webブラウザーではなく、ナビゲーションを処理する一部の表示アプリケーション（HTMLヘルプやQtヘルプ形式など）に埋め込まれることを意図している場合はTrue。この場合、サイドバーは含まれません。

favicon_url

現在のドキュメントからのHTMLファビコン画像への相対パス、またはファビコンへのURL、または''。

バージョン 4.0 で追加。

file_suffix

ビルダーのout_suffix属性の値。つまり、出力ファイルに付与されるファイル名拡張子です。標準のHTMLビルダーの場合、通常は.htmlです。

has_source

reStructuredTextドキュメントのソースがコピーされる場合はTrue（html_copy_sourceがTrueの場合）。

language

languageの値。

last_updated

ビルド日。

logo_url

現在のドキュメントからのHTMLロゴ画像への相対パス、またはロゴへのURL、または''。

バージョン 4.0 で追加。

master_doc

root_docと同じ。

バージョン 4.0 で変更: root_docに名前が変更されました。

root_doc

root_docの値。pathto()で使用します。

バージョン 4.0 で変更: master_docから名前が変更されました。

pagename

現在のファイルの「ページ名」。つまり、ファイルがreStructuredTextソースから生成された場合はドキュメント名、または出力ディレクトリに対する同等の階層名（[directory/]filename_without_extension）。

project

projectの値。

release

releaseの値。

「次へ」と「前へ」の横のrelbarの左側に配置するリンクのリスト。通常、これには、一般的なインデックスや、Pythonモジュールインデックスなどの他のインデックスへのリンクが含まれます。自分で何かを追加する場合は、タプル(pagename, link title, accesskey, link text)にする必要があります。

shorttitle

html_short_titleの値。

show_source

html_show_sourcelinkがTrueの場合はTrue。

sphinx_version

ビルドに使用されたSphinxのバージョンを、たとえば「3.5.1」のような文字列として表したものです。

sphinx_version_tuple

ビルドに使用されたSphinxのバージョンを、5つの要素のタプルとして表したものです。Sphinxバージョン3.5.1 beta 3の場合、これは(3, 5, 1, 'beta', 3)になります。4番目の要素は、alpha、beta、rc、finalのいずれかになります。finalの最後の要素は常に0です。

バージョン 4.2 で追加。

docutils_version_info

ビルドに使用されたDocutilsのバージョンを、5つの要素のタプルとして表したものです。Docutilsバージョン0.16.1 beta 2の場合、これは(0, 16, 1, 'beta', 2)になります。4番目の要素は、alpha、beta、candidate、finalのいずれかになります。finalの最後の要素は常に0です。

バージョン 5.0.2 で追加。

styles

テーマまたはhtml_styleで指定されたメインのスタイルシートの名前のリスト。

バージョン 5.1 で追加されました。

title

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

use_opensearch

html_use_opensearchの値。

version

versionの値。

これらの値に加えて、すべてのテーマオプション（theme_をプレフィックスとする）、およびhtml_contextでユーザーによって指定された値も利用できます。

ソースファイルから作成されたドキュメント（モジュールインデックスのような自動生成ファイルや、既にHTML形式のドキュメントとは対照的に）、これらの変数も利用可能です

body

テーマが適用される前に、HTMLビルダーによって生成されたHTML形式のページのコンテンツを含む文字列。

display_toc

tocに複数のエントリが含まれている場合はTrueのブール値。

meta

ドキュメントのメタデータ（辞書）、ファイル全体のメタデータを参照してください。

metatags

ページのHTMLmetaタグを含む文字列。

next

ナビゲーションの次のドキュメント。この変数はfalseであるか、linkとtitleの2つの属性を持ちます。titleにはHTMLマークアップが含まれます。たとえば、次のページへのリンクを生成するには、次のスニペットを使用できます。

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

レンダリングされたファイルのサフィックス。source_suffixのリストをサポートしているため、元のソースファイルに適切にリンクできます。

parents

nextアイテムのように構造化されたナビゲーション用の親ドキュメントのリスト。

prev

nextと同様ですが、前のページ用です。

sourcename

現在のドキュメントのコピーされたソースファイルの名前。これは、html_copy_sourceの値がTrueの場合にのみ空ではありません。これは、自動生成ファイルの作成時には空の値になります。

toc

現在のページのローカル目次。HTMLの箇条書きリストとしてレンダリングされます。

toctree

現在のページを含むグローバルTOCツリーを生成する呼び出し可能な関数。HTMLの箇条書きリストとしてレンダリングされます。オプションのキーワード引数

collapse

trueの場合、現在のページの子孫ではないすべてのTOCエントリが折りたたまれます。デフォルトはTrueです。

maxdepth

ツリーの最大深度。無制限の深さを許可するには、-1に設定します。デフォルトは、toctreeディレクティブで選択された最大深度です。

titles_only

trueの場合、ツリーに最上位のドキュメントタイトルのみを配置します。デフォルトはFalseです。

includehidden

trueの場合、ToCツリーには非表示のエントリも含まれます。デフォルトはFalseです。