HTMLテーマのサポート

バージョン 0.6 で追加.

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

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

テーマを使用する

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

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

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

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

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

3つ目の方法として、テーマのパスを動的に提供する方法があります。このためには setuptools がインストールされている必要があります。あなたが提供するテーマにsetup.pyを用意し、entry_pointsの sphinx_themes セクションに、テーマのパスを返す関数を get_path という名前で登録します:

# 'setup.py'

setup(
    ...
    entry_points = {
        'sphinx_themes': [
            'path = your_package:get_path',
        ]
    },
    ...
)

# 'your_package.py'

from os import path
package_dir = path.abspath(path.dirname(__file__))
template_path = path.join(package_dir, 'themes')

def get_path():
    return template_path

バージョン 1.2 で追加: entry_points の sphinx_themes 機能

組み込みテーマ

テーマ一覧  

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

Sphinxではテーマを選択できます。

テーマには次のようなものがあります。

  • basic – これは基本的にスタイルを持たないレイアウトで、他のテーマ用の基礎として使用されて、カスタムテーマの基礎としても同様に使用できます。 HTML にはサイドバーやリレーションバーのような重要な要素がすべて含まれています。以下のようなオプションがあります (それらは他のテーマによって継承されます):

    • nosidebar (true / false): サイドバーが含まれなくなります。デフォルトは False です。
    • sidebarwidth (整数): ピクセル単位で表されたサイドバーの幅。 (値に px を含めないでください。) デフォルトは 230 ピクセルです。
  • alabasterAlabaster theme は @kennethreitz が作った “Kr” Sphinxテーマ (Requestsプロジェクトで使われている)を調整したもので、その元になっているのは @mitsuhiko が作ったFlaskとその関連プロジェクトで使われているテーマです。テーマオプションの情報は Alabaster theme ページを参照してください。

  • classicPython 2のドキュメント とよく似たテーマです。以下のようなカスタマイズ用オプションを持っています:

    • rightsidebar (true / false): サイドバーを右側に表示します。デフォルトは False です。
    • stickysidebar (true / false): サイドバーを画面上に “固定” し、本体の長いコンテンツを見ているときでもスクロールしなくなります。この機能はすべてのブラウザでうまく動作するわけではありません。デフォルトは False です。
    • collapsiblesidebar (true / false): サイドバーの横に、サイドバーを折りたためるようにする、 実験的な JavaScriptを追加します。 これは”stickysidebar”と一緒には動作しません。 デフォルトは False です。
    • externalrefs (true / false): 外部リンクを、内部リンクと異なる表示にします。デフォルトは False です。

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

    • footerbgcolor (CSSカラー): フッターの背景色です。
    • footertextcolor (CSSカラー): フッターのテキストカラーです。
    • sidebarbgcolor (CSSカラー): サイドバーの背景色です。
    • sidebarbtncolor (CSSカラー): サイドバーの展開ボタンの背景色です(collapsiblesidebarTrue の時)。
    • 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カラー): ハイライトスタイルを設定していない場合に使用される、コードブロックのデフォルトのテキストカラーです。
    • bodyfont (CSS フォントファミリー): 通常のテキストのためのフォント。
    • headfont (CSS フォントファミリー): 見出しのためのフォント。
  • sphinxdoc – このドキュメンテーションに使用されているテーマ。右側のサイドバーが特徴です。現在のところ nosidebarsidebarwidth 以外のオプションはありません。

  • scrollsテンプレートエンジンのJinjaのドキュメント で使用されている、軽量なテーマです。次のような色に関するオプションがあります。

    • headerbordercolor
    • subheadlinecolor
    • linkcolor
    • visitedlinkcolor
    • admonitioncolor
  • agogo – Andi Albrechtが作ったテーマです。次のようなオプションが提供されています:

    • bodyfont (CSSフォントファミリー): 通常のテキストのフォントです。
    • headerfont (CSSフォントファミリー): 見出しのフォントです。
    • pagewidth (CSS長さ): ページのコンテンツの幅です。デフォルトは 70em です。
    • documentwidth (CSS長さ): ドキュメントの幅です。デフォルトは 50em です。
    • sidebarwidth (CSS長さ): サイドバーの幅です。デフォルトは 20em です。
    • bgcolor (CSSカラー): 背景の色です。
    • headerbg (CSSの”background”の値): ヘッダーの領域の背景です。デフォルトはグラデーションのかかったグレーです。
    • footerbg (CSSの”background”の値): フッターの領域の背景です。デフォルトはグラデーションのかかった明るいグレーです。
    • linkcolor (CSSカラー): Bodyのリンクのカラーです。
    • headercolor1, headercolor2 (CSSカラー): <h1>, <h2>の色です。
    • headerlinkcolor (CSSカラー): 見出しの逆参照のリンクの色です。
    • textalign (CSS text-align の値): Bodyのテキストの配置です。デフォルトは justify です。
  • nature – 緑色系のテーマ。現在のところ nosidebarsidebarwidth 以外のオプションはありません。

  • pyramid – Pyramid ウェブフレームワークプロジェクト由来のテーマ。 Blaise Laflamme によってデザインされました。現在のところ nosidebarsidebarwidth 以外のオプションはありません。

  • haikuHaiku OS user guide にインスパイアされた、サイドバーのないテーマです。次のようなオプションが提供されています:

    • full_logo (True/False デフォルトは False): もしTrueの場合は、ヘッダーには html_logo だけが表示されます。大きなロゴを使用するときに設定して下さい。Falseが設定されると、ロゴはフローティングで右寄せに表示され(あれば)、ドキュメントタイトルがヘッダに表示されます。
    • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS カラー): それぞれの要素の色。
  • traditional – 古い Python ドキュメントに似たテーマ。現在のところ nosidebarsidebarwidth 以外のオプションはありません。

  • epub – epub ビルダーのためのテーマ。このテーマは、 ebook リーダの希少な資源である視覚空間を節約しようとします。次のオプションがサポートされています:

    • relbar1 (true / false, デフォルトは true): これが True の場合、 relbar1 ブロックは epub 出力に挿入されます。そうでなければ省略されます。
    • footer (true / false, デフォルトは true): これが True の場合、 footer ブロックは epub 出力に挿入されます。そうでなければ省略されます。
  • bizstyle – シンプルな青みがかったテーマ。 nosidebarsidebarwidth オプションがサポートされます:
    • rightsidebar (true / false): サイドバーを右側に表示します。デフォルトは False です。

バージョン 1.3 で追加: ‘alabaster’, ‘sphinx_rtd_theme’, ‘bizstyle’ テーマ。

バージョン 1.3 で変更: default’テーマは’classic’に名前が変更されました。’default’という名前はまだ使用できますが、これを使うと、新しい’alabaster’テーマのエイリアスだという通知が出力されます。

テーマを作成する

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

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

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

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename

[options]
variable = default value
  • inherit には、 “継承元のテーマ” もしくは none を指定します。もし見つからないテンプレートがあれば、継承元のテーマのテンプレートが使用されるようになります。ほとんどのテーマでは、 basic のテーマで使用されているのと同じように使用するのであれば、テンプレートをすべて提供する必要はありません。同様に、オプション、すべての静的なファイルも継承されます。
  • stylesheet にはHTMLのヘッダから参照される、CSSファイルの名前を設定します。CSSファイルを一つ以上提供したい場合には、CSSの @import を使用して他のCSSをインクルードするか、必要なだけ <link rel="stylesheet"> タグを追加する、カスタムのHTMLテンプレートを使用します。この設定は html_style の設定値で上書きされます。
  • pygments_style には、ハイライトに使用する、Pygmentsのスタイルの名前を設定します。この設定は、コンフィグ値の pygments_style を使用することで、上書きできます。
  • options セクションには変数名と、デフォルト値のペアを記述していきます。これらのオプションは、 html_theme_options を設定することで、ユーザ側で上書きできます。また、すべてのテンプレートからは、 theme_<名前> として、この設定値にアクセスできます。

テンプレート

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

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

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

静的テンプレート

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

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

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

Third Party Themes

テーマ一覧  

sphinx_rtd_theme

sphinx_rtd_theme

 
  • sphinx_rtd_themeRead the Docs Sphinx Theme. これはモバイルでも使いやすいSphinxのテーマで、 readthedocs.org のために作られました。動作しているデモを readthedocs.org で確認できます。インストールとオプションの情報は Read the Docs Sphinx Theme ページを参照してください。

    バージョン 1.4 で変更: **sphinx_rtd_theme*はオプショナルになりました。