HTML テーマ

Sphinxは、HTMLおよびHTMLベースのフォーマット用のビルダを多数提供しています。

ビルダ

テーマ

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

注記

このセクションでは、既存のHTMLテーマの使用方法について説明します。独自のテーマを作成する場合は、HTMLテーマ開発を参照してください。

Sphinxは、*テーマ* を介してHTML出力の外観を変更することをサポートしています。テーマは、HTMLテンプレート、スタイルシート、その他の静的ファイルのコレクションです。さらに、どのテーマを継承するか、どの強調表示スタイルを使用するか、テーマのルックアンドフィールをカスタマイズするためのオプションなどを指定する設定ファイルがあります。

テーマはプロジェクトに依存しないように設計されているため、変更なしで異なるプロジェクトに使用できます。

テーマの使い方

Sphinxに付属のテーマを使用するのは簡単です。これらはインストールする必要がないため、html_theme 設定値を設定するだけで済みます。たとえば、classicテーマを有効にするには、conf.py に以下を追加します。

html_theme = "classic"

html_theme_options 設定値を使用して、テーマ固有のオプションを設定することもできます。これらのオプションは、一般的にテーマのルックアンドフィールを変更するために使用されます。たとえば、サイドバーを右側に配置し、関連バー（ページの上部と下部にあるナビゲーションリンクのあるバー）の背景を黒にするには、conf.py に以下を追加します。

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

テーマがSphinxに付属していない場合は、2つの静的フォームまたはPythonパッケージとして提供されます。静的フォームの場合、ディレクトリ（theme.toml とその他の必要なファイルを含む）または同じ内容のzipファイルがサポートされています。ディレクトリまたはzipファイルは、Sphinxが見つけられる場所に配置する必要があります。このためには、設定値 html_theme_path があります。これは、conf.py を含むディレクトリを基準とした、テーマディレクトリまたはzipファイルを含むことができるディレクトリのリストです。たとえば、blue.zip ファイルにテーマがある場合、conf.py を含むディレクトリに直接配置し、この設定を使用できます。

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

3番目の形式はPythonパッケージです。使用したいテーマがPythonパッケージとして配布されている場合は、インストール後に使用できます。

# installing theme package
$ pip install sphinxjp.themes.dotted

インストールしたら、ディレクトリまたはzipファイルベースのテーマと同じ方法で使用できます。

html_theme = "dotted"

独自のテーマの作成に関する情報など、テーマの設計の詳細については、HTMLテーマ開発を参照してください。

組み込みテーマ

テーマ概要

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

Sphinxには、選択できるテーマがいくつか付属しています。

これらのテーマのうち、モバイル向けに最適化されているのはAlabasterとScrollsテーマのみであり、他のテーマは画面が狭すぎる場合に横スクロールに頼ります。

これらのテーマは次のとおりです。

basic

これは、他のテーマのベースとして使用される、基本的にスタイルのないレイアウトであり、カスタムテーマのベースとしても使用できます。HTMLには、サイドバーや関連バーなど、すべての重要な要素が含まれています。これらのオプションがあります（他のテーマによって継承されます）。

  • **nosidebar** (true または false): サイドバーを含めません。デフォルトは False です。

  • **sidebarwidth** (int または str): サイドバーの幅（ピクセル単位）。これは、ピクセルとして解釈されるint、または '70em' や '50%' などの有効なCSSディメンション文字列です。デフォルトは230ピクセルです。

  • **body_min_width** (int または str): ドキュメント本文の最小幅。これは、ピクセルとして解釈されるint、または '70em' や '50%' などの有効なCSSディメンション文字列です。幅制限を設けない場合は0を使用します。デフォルトはテーマによって異なる場合があります（多くの場合450px）。

  • **body_max_width** (int または str): ドキュメント本文の最大幅。これは、ピクセルとして解釈されるint、または '70em' や '50%' などの有効なCSSディメンション文字列です。幅制限を設けない場合は「none」を使用します。デフォルトはテーマによって異なる場合があります（多くの場合800px）。

  • **navigation_with_keys** (true または false): 次のキーボードショートカットでナビゲートできるようにします。

    • 左 矢印キー: 前のページ

    • 右 矢印キー: 次のページ

    デフォルトは False です。

  • **enable_search_shortcuts** (true または false): / で検索ボックスにジャンプできるようにし、Esc で検索の強調表示を削除できるようにします。

    デフォルトは True です。

  • **globaltoc_collapse** (true または false): globaltoc.html (html_sidebars 参照) 内の現在のドキュメントのサブセクションのみを展開します。デフォルトは True です。

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

  • **globaltoc_includehidden** (true または false): toctree ディレクティブの :hidden: フラグで含まれているサブセクションも globaltoc.html (html_sidebars 参照) に表示します。デフォルトは False です。

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

  • **globaltoc_maxdepth** (int): globaltoc.html (html_sidebars 参照) 内の目次ツリーの最大深度。無制限の深さを許可するには、-1 に設定します。デフォルトは、toctreeディレクティブで選択された最大深度です。

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

alabaster

Alabasterテーマ は、@kennethreitzの修正版「Kr」Sphinxテーマ（特に彼のRequestsプロジェクトで使用されている）であり、それ自体がもともと@mitsuhikoのFlaskおよび関連プロジェクトで使用されているテーマに基づいています。その使用 html_sidebars を設定する方法については、インストールページ を参照してください。

classic

これは Python 2ドキュメント のような外観のクラシックテーマです。これらのオプションでカスタマイズできます。

  • **rightsidebar** (true または false): サイドバーを右側に配置します。デフォルトは False です。

  • **stickysidebar** (true または false): サイドバーを「固定」して、長い本文コンテンツでもスクロールして見えなくならないようにします。これは、すべてのブラウザでうまく機能するとは限りません。デフォルトは False です。

  • **collapsiblesidebar** (true または false): サイドバーを側面のボタンで折りたたみ可能にする *実験的な* JavaScriptスニペットを追加します。デフォルトは False です。

  • **externalrefs** (true または false): 外部リンクを内部リンクと区別して表示します。デフォルトは False です。

カスタムスタイルシートを作成せずにカラースキームを変更できる、さまざまな色とフォントのオプションもあります。

  • **footerbgcolor** (CSS カラー): フッター行の背景色。

  • **footertextcolor** (CSS カラー): フッター行のテキストの色。

  • **sidebarbgcolor** (CSS カラー): サイドバーの背景色。

  • **sidebarbtncolor** (CSS カラー): サイドバーの折りたたみボタンの背景色（ *collapsiblesidebar* が True の場合に使用されます）。

  • **sidebartextcolor** (CSS カラー): サイドバーのテキストの色。

  • **sidebarlinkcolor** (CSS カラー): サイドバーのリンクの色。

  • **relbarbgcolor** (CSS カラー): 関連バーの背景色。

  • **relbartextcolor** (CSS カラー): 関連バーのテキストの色。

  • **relbarlinkcolor** (CSS カラー): 関連バーのリンクの色。

  • **bgcolor** (CSS カラー): 本文の背景色。

  • **textcolor** (CSS カラー): 本文のテキストの色。

  • **linkcolor** (CSS カラー): 本文のリンクの色。

  • **visitedlinkcolor** (CSS カラー): 訪問済みリンクの本文の色。

  • **headbgcolor** (CSS カラー): 見出しの背景色。

  • **headtextcolor** (CSS カラー): 見出しのテキストの色。

  • **headlinkcolor** (CSS カラー): 見出しのリンクの色。

  • **codebgcolor** (CSS カラー): コードブロックの背景色。

  • **codetextcolor** (CSS カラー): 強調表示スタイルで別に設定されていない場合の、コードブロックのデフォルトのテキストの色。

  • **bodyfont** (CSS font-family): 通常のテキストのフォント。

  • **headfont** (CSS font-family): 見出しのフォント。

sphinxdoc

このドキュメントで元々使用されていたテーマです。右側にサイドバーがあります。現在、_nosidebar_ と _sidebarwidth_ 以外のオプションはありません。

注記

Sphinx ドキュメントは現在、sphinxdoc テーマの調整版を使用しています。

scrolls

Jinja ドキュメントをベースにした、より軽量なテーマです。以下のカラーオプションが利用可能です。

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

Andi Albrecht によって作成されたテーマです。以下のオプションがサポートされています。

  • bodyfont (CSS font family): 通常テキストのフォント。

  • headerfont (CSS font family): 見出しのフォント。

  • pagewidth (CSS length): ページコンテンツの幅。デフォルトは 70em。

  • documentwidth (CSS length): ドキュメントの幅（サイドバーを除く）。デフォルトは 50em。

  • sidebarwidth (CSS length): サイドバーの幅。デフォルトは 20em。

  • rightsidebar (true または false): サイドバーを右側に配置します。デフォルトは True です。

  • bgcolor (CSS color): 背景色。

  • headerbg (CSS の "background" 値): ヘッダー領域の背景。デフォルトは灰色がかったグラデーション。

  • footerbg (CSS の "background" 値): フッター領域の背景。デフォルトは薄い灰色のグラデーション。

  • **linkcolor** (CSS カラー): 本文のリンクの色。

  • headercolor1, headercolor2 (CSS color): <h1> および <h2> 見出しの色。

  • headerlinkcolor (CSS color): 見出しのバックリファレンスリンクの色。

  • textalign (CSS の _text-align_ 値): 本文のテキスト配置。デフォルトは justify です。

nature

緑がかったテーマです。現在、_nosidebar_ と _sidebarwidth_ 以外のオプションはありません。

pyramid

Blaise Laflamme によってデザインされた、Pyramid ウェブフレームワークプロジェクトのテーマです。現在、_nosidebar_ と _sidebarwidth_ 以外のオプションはありません。

haiku

Haiku OS ユーザーガイド にインスパイアされた、サイドバーのないテーマです。以下のオプションがサポートされています。

  • full_logo (true または false、デフォルトは False): true の場合、ヘッダーには html_logo のみが表示されます。大きなロゴに使用します。false の場合、ロゴ（存在する場合）は右側にフローティング表示され、ドキュメントのタイトルがヘッダーに配置されます。

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS colors): さまざまな本文要素の色。

traditional

古い Python ドキュメントに似たテーマです。現在、_nosidebar_ と _sidebarwidth_ 以外のオプションはありません。

epub

epub ビルダー用のテーマです。このテーマは、電子書籍リーダーでは乏しいリソースである視覚的なスペースを節約しようとします。以下のオプションがサポートされています。

  • relbar1 (true または false、デフォルトは True): true の場合、relbar1 ブロックが epub 出力に挿入されます。そうでない場合は省略されます。

  • footer (true または false、デフォルトは True): true の場合、footer ブロックが epub 出力に挿入されます。そうでない場合は省略されます。

bizstyle

シンプルな青みがかったテーマです。_nosidebar_ と _sidebarwidth_ 以外にも以下のオプションがサポートされています。

  • **rightsidebar** (true または false): サイドバーを右側に配置します。デフォルトは False です。

バージョン 1.3 で追加: 「alabaster」、「sphinx_rtd_theme」、および「bizstyle」テーマ。

バージョン 1.3 で変更: 「default」テーマの名前が「classic」に変更されました。「default」はまだ利用可能ですが、新しい「alabaster」テーマのエイリアスであるという通知が表示されます。

サードパーティテーマ

Sphinx 用に作成されたサードパーティテーマは多数あります。これらのいくつかは一般的な用途向けであり、その他は個々のプロジェクトに固有のものです。

sphinx-themes.org は、Sphinx のさまざまなテーマを紹介するギャラリーで、各テーマでレンダリングされたデモドキュメントがあります。テーマは、PyPI (分類子 Framework :: Sphinx :: Theme を使用)、GitHub、および GitLab でも見つけることができます。