HTMLテーマのサポート

バージョン 0.6 で追加.

注釈

This document provides information about creating your own theme. If you simply wish to use a pre-existing HTML themes, refer to HTML.

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

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

テーマを作成する

Themes take the form of either a directory or a zipfile (whose name is the theme name), containing the following:

  • A theme.conf file.

  • HTMLテンプレート(必要に応じて)

  • ビルド時に出力のディレクトリにコピーされる静的ファイルを含む static/ ディレクトリ。画像、スタイルシート、スクリプトファイルなどです。

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

[theme]
inherit = base theme
stylesheet = main CSS name
pygments_style = stylename
sidebars = localtoc.html, relations.html, sourcelink.html, searchbox.html

[options]
variable = default value
  • The inherit setting gives the name of a "base theme", or none. The base theme will be used to locate missing templates (most themes will not have to supply most templates if they use basic as the base theme), its options will be inherited, and all of its static files will be used as well. If you want to also inherit the stylesheet, include it via CSS' @import in your own.

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

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

  • The sidebars setting gives the comma separated list of sidebar templates for constructing sidebars. This can be overridden by the user in the html_sidebars config value.

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

バージョン 1.7 で追加: sidebar settings

Distribute your theme as a Python package

As a way to distribute your theme, you can use Python package. Python package brings to users easy setting up ways.

To distribute your theme as a Python package, please define an entry point called sphinx.html_themes in your setup.py file, and write a setup() function to register your themes using add_html_theme() API in it:

# 'setup.py'
setup(
    ...
    entry_points = {
        'sphinx.html_themes': [
            'name_of_theme = your_package',
        ]
    },
    ...
)

# 'your_package.py'
from os import path

def setup(app):
    app.add_html_theme('name_of_theme', path.abspath(path.dirname(__file__)))

If your theme package contains two or more themes, please call add_html_theme() twice or more.

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

バージョン 1.6 で非推奨: sphinx_themes entry_points has been deprecated.

バージョン 1.6 で追加: sphinx.html_themes entry_points feature.

テンプレート

もし自分でテンプレートを書こうと思っている場合には、 テンプレートガイド を読むと参考になるでしょう。テンプレートに関して知っておくべきことは、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ファイルではありません。これは、テーマが共有されても、不必要なセキュリティのリスクを抱えないようにするために、このようになっています。