HTML

Sphinx provides a number of builders for HTML and HTML-based formats.

Builders

課題

Populate when the 'builders' document is split up.

Themes

バージョン 0.6 で追加.

注釈

This section provides information about using pre-existing HTML themes. If you wish to create your own theme, refer to HTMLテーマのサポート.

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

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

テーマを使用する

Using a theme provided with Sphinx is easy. Since these do not need to be installed, you only need to set the html_theme config value. For example, to enable the classic theme, add the following to conf.py:

html_theme = "classic"

You can also set theme-specific options using the html_theme_options config value. These options are generally used to change the look and feel of the theme. For example, to place the sidebar on the right side and a black background for the relation bar (the bar with the navigation links at the page's top and bottom), add the following conf.py:

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

If the theme does not come with Sphinx, it can be in two static forms or as a Python package. For the static forms, either a directory (containing theme.conf and other needed files), or a zip file with the same contents is supported. The directory or zipfile must be put where Sphinx can find it; for this there is the config value html_theme_path. This can be a list of directories, relative to the directory containing conf.py, that can contain theme directories or zip files. For example, if you have a theme in the file blue.zip, you can put it right in the directory containing conf.py and use this configuration:

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

The third form is a Python package. If a theme you want to use is distributed as a Python package, you can use it after installing

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

Once installed, this can be used in the same manner as a directory or zipfile-based theme:

html_theme = "dotted"

For more information on the design of themes, including information about writing your own themes, refer to HTMLテーマのサポート.

組み込みテーマ

テーマ一覧

alabaster

alabaster

classic

classic

sphinxdoc

sphinxdoc

scrolls

scrolls

agogo

agogo

traditional

traditional

nature

nature

haiku

haiku

pyramid

pyramid

bizstyle

bizstyle

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

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

basic

This is a basically unstyled layout used as the base for the other themes, and usable as the base for custom themes as well. The HTML contains all important elements like sidebar and relation bar. There are these options (which are inherited by the other themes):

  • nosidebar (true / false): サイドバーが含まれなくなります。デフォルトは False です。

  • sidebarwidth (整数もしくは文字列): ピクセル単位で表されたサイドバーの幅。整数の場合はピクセル数として解釈されます。そうでない場合は、'70em'や 50%'のような有効なCSSディメンジョン文字列を指定します。 デフォルトは 230 ピクセルです。

  • body_min_width (int or str): Minimal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as '70em' or '50%'. Use 0 if you don't want a width limit. Defaults may depend on the theme (often 450px).

  • body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as '70em' or '50%'. Use 'none' if you don't want a width limit. Defaults may depend on the theme (often 800px).

alabaster

Alabaster theme is a modified "Kr" Sphinx theme from @kennethreitz (especially as used in his Requests project), which was itself originally based on @mitsuhiko's theme used for Flask & related projects. Refer to its installation page for information on how to configure html_sidebars for its use.

classic

This is the classic theme, which looks like the Python 2 documentation. It can be customized via these options:

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

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

  • collapsiblesidebar (true or false): Add an experimental JavaScript snippet that makes the sidebar collapsible via a button on its side. Defaults to 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

The theme originally used by this documentation. It features a sidebar on the right side. There are currently no options beyond nosidebar and sidebarwidth.

注釈

The Sphinx documentation now uses an adjusted version of the sphinxdoc theme.

scrolls

A more lightweight theme, based on the Jinja documentation. The following color options are available:

  • headerbordercolor

  • subheadlinecolor

  • linkcolor

  • visitedlinkcolor

  • admonitioncolor

agogo

A theme created by Andi Albrecht. The following options are supported:

  • 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

A greenish theme. There are currently no options beyond nosidebar and sidebarwidth.

pyramid

A theme from the Pyramid web framework project, designed by Blaise Laflamme. There are currently no options beyond nosidebar and sidebarwidth.

haiku

A theme without sidebar inspired by the Haiku OS user guide. The following options are supported:

  • full_logo (True/False デフォルトは False): もしTrueの場合は、ヘッダーには html_logo だけが表示されます。大きなロゴを使用するときに設定して下さい。Falseが設定されると、ロゴはフローティングで右寄せに表示され(あれば)、ドキュメントタイトルがヘッダに表示されます。

  • textcolor, headingcolor, linkcolor, visitedlinkcolor, hoverlinkcolor (CSS カラー): それぞれの要素の色。

traditional

A theme resembling the old Python documentation. There are currently no options beyond nosidebar and sidebarwidth.

epub

A theme for the epub builder. This theme tries to save visual space which is a sparse resource on ebook readers. The following options are supported:

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

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

bizstyle

A simple bluish theme. The following options are supported beyond nosidebar and sidebarwidth:

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

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

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

サードパーティ製のテーマ

テーマ一覧

sphinx_rtd_theme

sphinx_rtd_theme

There are many third-party themes available. Some of these are general use, while others are specific to an individual project. A section of third-party themes is listed below. Many more can be found on PyPI, GitHub and sphinx-themes.org.

sphinx_rtd_theme

Read the Docs Sphinx Theme. This is a mobile-friendly sphinx theme that was made for readthedocs.org. View a working demo over on readthedocs.org. You can get install and options information at Read the Docs Sphinx Theme page.

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