HTMLテーマのサポート

バージョン 0.6 で追加.

Sphinxは テーマ を使って出力したHTMLの見た目を変更する機能をサポートしています。テーマというのは、HTMLのテンプレート、スタイルシート、およびその他の静的なファイル類を集めたものです。これに加えて、どのテーマから継承するか、どのようなハイライトのスタイルを使用するか、テーマのルックアンドフィールをカスタマイズするためにどのようなオプションがあるのか、といったことが書かれている設定ファイルがあります。

テーマというのは特定のプロジェクトに依存しないものです。そのため、他のプロジェクトに適用する際に変更する必要はありません。

テーマを使用する

既存のテーマを使用するのは簡単です。Sphinxに組み込みのテーマであれば、 html_theme という設定値をセットするだけです。 html_theme_options を使うと、そのテーマ特有の設定値を指定することができ、ルックアンドフィールを変更することができます。以下のように、 conf.py に記述します:

html_theme = "default"
html_theme_options = {
    "rightsidebar": "true",
    "relbarbgcolor": "black"
}

この設定は、デフォルトのテーマを使用して、サイドバーを右に表示し、リレーションバー(ページの最上部と最下部の両方に表示される、ナビゲーションのリンクを持つバー)の背景色を黒に設定します。

Sphinxに組み込まれていないテーマを利用する方法は2通りの方法があります。 theme.conf とその他の必要なファイルの入ったディレクトリで指定する方法と、同様のファイルが入っているzipファイルを指定する方法です。どちらを使用するにしても、Sphinxから見つけられるように、 html_theme_path の設定を行う必要があります。この設定には、ディレクトリやzipファイルのテーマが入っているディレクトリのリストを設定します。パスは conf.py からの相対パスで設定します。例えば、 conf.py と同じディレクトリにある blue.zip というファイルを設定するとしたら、以下のように設定します:

html_theme = "blue"
html_theme_path = ["."]

組み込みテーマ

Sphinxでは以下のテーマから選択することができます。

• basic – default や sphinxdoc のテーマのベースとして使用されているテーマです。基本的にレイアウトなどは設定されていません。これはカスタムテーマを作成するのに使用することができます。このHTMLには、サイドバーやリレーションバーなどの重要な要素はすべて含まれています。このテーマは一つのオプションを持っています。このオプションは default, sphinxdoc にも継承されます。
  • nosidebar (true / false): サイドバーが含まれなくなります。デフォルトは false です。

• default – デフォルトのテーマです。以下のようなカスタマイズ用オプションを持っています:

  • rightsidebar (true / false): サイドバーを右側に表示します。デフォルトは false です。
  • stickysidebar (true / false): サイドバーを画面上に “固定” し、本体の長いコンテンツを見ているときでもスクロールしなくなります。この機能はすべてのブラウザでうまく動作するわけではありません。デフォルトは false です。

  カスタムのスタイルシートを作成しなくても、カラースキームを変更できるように、数多くの色、フォントに関するオプションを持っています。

  • footerbgcolor (CSSカラー): フッターの背景色です。
  • footertextcolor (CSSカラー): フッターのテキストカラーです。
  • sidebarbgcolor (CSSカラー): サイドバーの背景色です。
  • sidebartextcolor (CSSカラー): サイドバーのテキストカラーです。
  • sidebarlinkcolor (CSSカラー): サイドバーのリンクの色です。
  • relbarbgcolor (CSSカラー): リレーションバーの背景色です。
  • relbartextcolor (CSSカラー): リレーションバーのテキストカラーです。
  • relbarlinkcolor (CSSカラー): リレーションバーのリンクの色です。
  • bgcolor (CSSカラー): Bodyの背景色です。
  • textcolor (CSSカラー): Bodyのテキストカラーです。
  • linkcolor (CSSカラー): Bodyのリンクのカラーです。
  • visitedlinkcolor (CSSカラー): 訪れたリンクのカラーです。
  • headbgcolor (CSSカラー): 見出しの背景色です。
  • headtextcolor (CSSカラー): 見出しのテキストカラーです。
  • headlinkcolor (CSSカラー): 見出しのリンクの色です。
  • codebgcolor (CSSカラー): コードブロックの背景色です。
  • codetextcolor (CSSカラー): ハイライトスタイルを設定していない場合に使用される、コードブロックのデフォルトのテキストカラーです。

• sphinxdoc – このドキュメントで使用されているテーマです。このテーマではサイドバーが右側に表示されます。このテーマには nosidebar 以外のオプションはありません。

• traditional – 古いPythonのドキュメントに似たテーマです。 nosidebar 以外のオプションはありません。

テーマを作成する

すでに説明している通り、テーマは以下のファイルを持つディレクトリかzipファイルです。ディレクトリ名かzipファイルの名前がテーマ名になります:

• theme.conf ファイル
• HTMLテンプレート(必要に応じて)
• ビルド時に出力のディレクトリにコピーされる静的ファイルを含む static/ ディレクトリ。画像、スタイルシート、スクリプトファイルなどです。

theme.conf ファイルは Pythonの標準ライブラリの ConfigParser モジュールで読み込み可能な INIフォーマット [1] で記述します。以下のような構造になっています:

[theme]
inherit = 継承元のテーマ
stylesheet = メインのCSS名
pygments_style = スタイル名

[options]
変数 = デフォルト値

inherit には、 “継承元のテーマ” もしくは none を指定します。もし見つからないテンプレートがあれば、継承元のテーマのテンプレートが使用されるようになります。ほとんどのテーマでは、 basic のテーマで使用されているのと同じように使用するのであれば、テンプレートをすべて提供する必要はありません。同様に、オプション、すべての静的なファイルも継承されます。

• stylesheet にはHTMLのヘッダから参照される、CSSファイルの名前を設定します。CSSファイルを一つ以上提供したい場合には、CSSの @import を使用して他のCSSをインクルードするか、必要なだけ <link rel="stylesheet"> タグを追加する、カスタムのHTMLテンプレートを使用します。

• pygments_style には、ハイライトに使用する、Pygmentsのスタイルの名前を競ってします。この設定は、コンフィグ値の pygments_style を使用することで、上書きすることができます。

• options セクションには変数名と、デフォルト値のペアを記述していきます。これらのオプションは、 html_theme_options を設定することで、ユーザ側で上書きすることができます。また、すべてのテンプレートからは、 theme_<名前> として、この設定値にアクセスすることができます。

テンプレート

もし自分でテンプレートを書こうと思っている場合には、 テンプレートガイド を読むと参考になるでしょう。テンプレートに関して知っておくべきことは、Sphinxがテンプレートを探索する順序です:

• 最初は、ユーザの templates_path ディレクトリ
• その次は、選択されたテーマ内
• それから先は、テーマの継承元のテーマを順に探索

継承元のテーマに含まれるテンプレートと同名のテンプレートを作成して、拡張する場合には、 {% extends "継承元のテーマ名/layout.html" %} という風にテーマ名をディレクトリとして明示することで行うことができます。ユーザの templates_path の中のテンプレートでも、 “エクスクラメーションマーク(!)” のシンタックスを使用して、テンプレートのドキュメント内であると指定することもできます。

静的テンプレート

テーマオプションを使用すると、ユーザがカスタムのスタイルシートを書く必要もなく、テーマを簡単にカスタマイズできるようになります。これはHTMLファイルと同じように、テンプレート静的ファイルでも行うことができます。Sphinxはこのために、”静的テンプレート”と呼ばれるものをサポートしています。

もし、テーマの中の static/ ディレクトリ(もしくはユーザの静的ファイルパス)の中に、末尾が _t のファイルがあったとすると、そのファイルはテンプレートエンジンによって処理されます。 _t は最終的なファイル名からは除外されます。例えば、 default テーマは static/default.css_t というファイルを持っていますが、これは色のオプションを持ったスタイルシートのテンプレートです。ドキュメントがビルドされる時に、すべてのテンプレートタグが処理されて、色のオプションがスタイルシートに書き込まれて、出力ディレクトリには _static/default.css ファイルとして出力されます。

[1]	これは conf.py とは異なり、実行可能はPythonファイルではありません。これは、テーマが共有されても、不必要なセキュリティのリスクを抱えないようにするために、このようになっています。