テンプレート化する

Sphinx使用 Jinja そのHTMLテンプレートのテンプレートエンジン.Jinsaはテキストベースのエンジンで、Djangoテンプレートからインスピレーションを得ているので、Djangoを使ったことのある人は誰でも知っているはずです。それはまたそれを熟知しなければならない人たちに素晴らしい文書を提供する。

Sphinxのテンプレートを使ってHTMLを生成する必要がありますか？

违うよ。他にもいくつかの選択肢があります

  • 作成することができます TemplateBridge 選択されたテンプレートエンジンのサブクラスを呼び出し、 template_bridge 対応する構成値。

  • 君ならできる write a custom builder これは StandaloneHTMLBuilder 選択したテンプレートエンジンを呼び出します。

  • ご利用いただけます PickleHTMLBuilder これは，ページ内容を含むPickleファイルを生成し，カスタムツールを用いて後処理したり，Webアプリケーションで使用したりする.

金佳/ライオンの顔像テンプレートプライマー

Sphinxにおけるデフォルトテンプレート言語はJJJAである.これはDjango/Smartyのインスピレーションで、理解しやすい。金家の最も重要な概念は template inheritance これは、変更を最小限に保ちながら、テンプレート内の特定のブロックしかカバーできないことを意味します。

文書の出力をカスタマイズするためには，すべてのテンプレート(レイアウトテンプレートとサブテンプレート)を上書きすることができ，Sphinx QuickStartが生成した構造のテンプレートディレクトリにオリジナルファイル名と同じファイルを追加する方法である.

Sphinxは、以下のフォルダでテンプレートを検索します。 templates_path まず，そこで探しているテンプレートが見つからなければ，選択されたトピックのテンプレートに戻る.

テンプレートは含まれています 変数.変数 テンプレートを評価する際には，これらの値は値に置き換えられる. tags テンプレートの論理を制御し 積み木 これらはテンプレート継承に用いられる.

獅子面像 基本型. Themeは基本テンプレートにいくつかのブロックを提供し、それらはデータを充填する。彼らは位置しています themes/basic Sphinxインストールディレクトリのサブディレクトリは、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() }}}} 拡張テンプレート内にブロックの元のコンテンツの位置が提示されます。コンテンツを表示したくない限り。

内蔵テンプレートの使用

建築 基本型. Themeは、Sphinx引数を内蔵したすべてのテンプレートを提供します。これには以下の要素が含まれており、それらをカバーまたは使用することができます。

積み木

次のブロックは layout.html テンプレート：

doctype

出力フォーマットのdoctype。デフォルトでは、これはXHTML 1.0変換であり、SphinxとDocutilsが生成した内容に最も近いので、HTML 5または異なるが互換性のあるXHTML doctypeに切り替えたい場合がない限り、変更しないことが望ましい。

linktags

このブロックはいくつ追加されましたか <link> テンプレートのヘッダ部分にタグを付加する.

extrahead

デフォルトの場合、このブロックは空であり、追加のコンテンツを追加するために使用されてもよい <head> 生成されたHTML文書のタグ.これはJavaScriptまたは追加のCSSファイルへの参照を追加する正しい位置である.

relbar1, relbar2

このブロックには 関係欄. .関連リンクのリスト(左側が親文書，右側がインデックス，モジュールなどへのリンク). relbar1 文書の前に現れて relbar2 書類の後に。デフォルトの場合、両方のブロックが充填されています。文書の前にrelbarのみを表示するには、書き換えることができます。 relbar2 以下のようになる.

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

Relbarの内部には3つの部分があります rootrellink 文書内のリンクとカスタマイズ relbaritems それがそうです。♪the rootrellink デフォルトの場合はマスター文書へのリスト項目を含むブロックであり，デフォルトの場合は relbaritems 空いている塊です。欄に追加リンクを追加するために書き換えた場合は、リスト項であることを確認してください reldelim1 それがそうです。

document

文書自体の内容。これはブロック“Body”を含み，各コンテンツは以下に示すサブテンプレートによって配置される. page.html それがそうです。

注釈

内蔵されたJavaScript検索が結果ページ上にページプレビューを表示するためには，文書や本文内容が含まれているように包装すべきである. role="main" 属性です。例えば：

<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つのブロックは only カスタムサイドバーリストが割り当てられていないページ使用 html_sidebars 値を配置する。これらの使用を推奨するのではなく、単独のサイドバーテンプレートをサポートすることは、以下のようにサイドバーテンプレートを含むことができる html_sidebars それがそうです。

sidebartoc

サイドバーのリスト。

バージョン 1.0 で非推奨.

sidebarrel

サイドバーにおける関係リンク(前，次の文書).

バージョン 1.0 で非推奨.

sidebarsourcelink

サイドバーの“Show source”リンク(通常、この機能を有効にしている場合にのみ表示されます 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はテンプレートに様々なJJJA関数をブースタとして提供する.これらを使用して、リンクを生成したり、複数回使用された要素を出力したりすることができ

pathto(document)

Sphinx文書への経路をURLとして返す.このオプションを使用して構築された文書を参照することができる.

pathto(file, 1)

経路を戻します file これは，生成された出力に対するルートのファイル名である.このオプションを使用して、静的ファイルを参照することができます。

hasdoc(document)

その名前を持つ文書が存在するかどうかをチェックする ドキュメント 存在しています

表示されたサイドバーに戻ります。

relbar()

提示された関係欄に戻ります。

warning(message)

警告メッセージを発する。

グローバル変数.

これらのグローバル変数は、各テンプレートにおいて利用可能であり、安全に使用することができる。もっと多くのことがありますが、ほとんどは細部事項を達成して、将来変更されるかもしれません。

builder

建築業者の名前(例えば html あるいは…。 htmlhelp ）。

の価値 copyright それがそうです。

docstitle

文書のタイトル(値) html_title )は、“単一ファイル”ビルダが使用されない限り、設定されている場合には None それがそうです。

embedded

生成されたHTMLが、HTMLヘルプまたはQtヘルプフォーマットのようなWebブラウザではなく、いくつかの処理ナビゲーションの閲覧アプリケーションに埋め込まれる場合、Trueとなる。この場合、サイドバーは含まれない。

favicon

静的パスにはHTMLにクリップ·ターゲット·パスが格納されているか，または '' それがそうです。

file_suffix

建築業者の価値 out_suffix 属性，すなわち出力ファイルが取得するファイル拡張子である.標準的なHTML構築器では .html それがそうです。

has_source

RESTファイルソースがコピーされていればTrue(であれば html_copy_source はい。 True ）。

language

の価値 language それがそうです。

last_updated

構築日。

静的経路におけるHTMLロゴ画像の経路，または '' それがそうです。

master_doc

の価値 master_doc 使用することができます pathto() それがそうです。

pagename

現在のファイルの“ページ名”、すなわち、ファイルがRESTソースから生成された場合、文書名、または出力ディレクトリに対する等価階層名である ([directory/]filename_without_extension ）。

project

の価値 project それがそうです。

release

の価値 release それがそうです。

Relbarの左側に置くリンクリストは，“Next”と“Prev”のすぐ隣にある.これには、一般に、Pythonモジュールインデックスのような通常のインデックスおよび他のインデックスへのリンクが含まれています。自分であるコンテンツを追加する場合、タプルでなければなりません (pagename, link title, accesskey, link text) それがそうです。

shorttitle

の価値 html_short_title それがそうです。

show_source

以下の条件を満たせば真となる html_show_sourcelink はい。 True それがそうです。

sphinx_version

構築のためのSphinxバージョン。

style

メインスタイル表の名称、主題または html_style それがそうです。

title

現在の文書のタイトルは <title> ラベル。

use_opensearch

の価値 html_use_opensearch それがそうです。

version

の価値 version それがそうです。

これらの値以外にも テーマ·オプション 利用可能(接頭辞は theme_ )と、ユーザが html_context それがそうです。

ソースファイルから作成された文書(モジュールインデックスまたはHTML形式の文書のような自動生成されたファイルとは逆)には、以下の変数を使用することもできる。

body

1つの文字列は、トピックを適用する前にHTML生成器によって生成されたHTMLフォームに含まれるページ内容である。

display_toc

ディレクトリに複数のエントリが含まれている場合、ブール値はTrueとなる。

meta

文書メタデータ(辞書)を参照されたい 文書範囲のメタデータ それがそうです。

metatags

ページを含むHTMLの文字列 meta ラベル。

next

ナビゲーションの次の文書です。この変数はFalseであるか，または2つの属性を持つ. link そして 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

1つのCallableは，現在のページを含むグローバルディレクトリ木を生成し，HTML項目記号リストとして提示する.オプションのキーワードパラメータ：

collapse

Trueである場合、折り畳みは、現在のページの先祖のすべてのディレクトリエントリではない。 True デフォルトの場合。

maxdepth

木の最大深さ。とする. -1 無限の深さを許すことができますデフォルトはtoctree命令で選択された最大深さである.

titles_only

Trueであれば，トップ文書タイトルのみを木に入れる. False デフォルトの場合。

includehidden

Trueである場合、ディレクトリツリーには隠れエントリも含まれる。 False デフォルトの場合。