テーマしたい（`html_theme`）

html_theme = "テーマ名"

Sphinxを使うときに必ず設定する項目のひとつです。 html_themeを使ってHTML出力のテーマ（＝スタイルを集めたもの）を設定できます。

テーマのオプションを設定したい（`html_theme_options`）

html_theme = "テーマ名"
html_theme_options = {
    "設定キー": "値",
    "設定キー": "値",
    ...,
}

html_theme_optionsを使って、テーマのオプションを設定できます。設定できる値はテーマごとに違うので、そのテーマのドキュメントを参照するのが適切です。

組み込みテーマのオプションも設定できます。ただし、組み込みテーマ自体の見た目が全体的にぱっとしないので、あまり出番はないかもしれません。他のテーマの中身を確認したり、自作テーマを作成したりするときの参考にはなると思います。

既存のテーマを使いたい

デフォルトはalabasterですが、あまり日本語向きではないと感じています。安定したオススメはsphinx_rtd_themeです。最近はsphinx_book_themeが気に入っています。 Sphinx Theme Galleryから自分の好みのテーマを探すことができます。

自作テーマしたい（`theme.conf`）

Sphinxのテーマは自作できます。が、いきなり自分で作るのは大変なので、既存のテーマのソースコードを読むときに、どのファイルを読めばいいのか確認しておきます。

まず設定ファイルtheme.confを確認します。これはconfigparserでパースできるini形式のファイルです。元となるテーマがある場合はinherit = 元にするテーマ名でいろいろ引き継ぐことができます。

CSSファイルはstylesheet = CSSファイル名,CSSファイル名,...で設定できます。カンマで区切って複数のファイルのリストを設定できます。このファイルはHTMLヘッダーで参照されます。この値はconf.pyのhtml_styleで上書きできます。

シンタックスハイライトはpygments_style = スタイル名で設定できます。この値はconf.pyのpygments_styleで上書きできます。

サイドバーはsidbar = テンプレート名,...で設定できます。この値はconf.pyのhtml_sidebarsで上書きできます。

テーマのオプションは[options]セクションに変数名 = デフォルト値の、いわゆるkey - value形式で設定できます。これらのオプション値はconf.pyのhtml_theme_optionsで上書きできます。また、すべてのテンプレートからはtheme_<名前>としてこの値にアクセスできます。

自作テンプレートしたい（`templates_path`）

テーマの引き継ぎとオプションの設定ができたら、次はテンプレートを追加する必要があります。 Sphinxでは以下の優先度でテンプレートが適用されます。

ユーザーテンプレート（＝conf.pyのtemplates_pathディレクトリのテンプレート）
選択したテーマのテンプレート
引き継いだテーマのテンプレート

SphinxのテンプレートエンジンはJinja2であるため、読み込まれたファイルはJinja2に食べられます。

ユーザーテンプレートしたい

{% extends "!layout.html" %}
<!doctype html>
<head>
<meta charset="utf-8">
<link href=".css">
</head>
    <div class="container">
    <main></main>
    <footer></footer>
    </div>
    <script></script>
</html>

layout.htmlというテンプレートを作成し、その中のブロック要素をカスタマイズします。

doctypeしたい

{% extends "!layout.html" %}
{% block doctype %}
<!doctype html>
{% endblock %}

{% block extrahead %}
<meta charset="utf-8">
{% endblock}

{% block footer %}
{% endblock %}

テーマしたい（html_theme）

テーマのオプションを設定したい（html_theme_options）