Sphinx Advent Calendar 16日目

sphinx log

Sphinx Advent Calendar 2012 - connpass の 16 日目です。
昨日は @cointoss1973 さんの pandoc で Redmine の Wiki を Sphinx に変換しよう - secretbase.log でした。

今日のハナシ

5 日目を担当された @togakushi さんが題材にしている Sphinx HTML テーマを、自分も取り上げてみようと思います。

HTML テーマ事始め - 日本語版

今年 9 月の SphinxCon JP 2012 で Sphinx HTML テーマを題材に発表をしたのですが、その発表の追補という位置づけです。

自作 HTML テーマを zip で配布する

SphinxCon JP 2012 の発表では自作のテーマのディレクトリ構成を提示して、そのディレクトリを直接指定してテーマを読み込ませる、という手法を紹介したわけですが、この手法には「複数人数で同じテーマを使いたい場合に、面倒くさい」という短所があります。

テーマを一つのディレクトリとして構成しているので、そのディレクトリをまるごと共用しないといけないわけです。ちょっとこれはイケてないですよね。

はて、どうしたものか... というところですが、 Sphinx の公式ドキュメントには以下のような記述があります :

If the theme does not come with Sphinx, it can be in two forms: either a directory (containing theme.conf and other needed files), or a zip file with the same contents.

テーマが Sphinx に付属していない場合、次の２つの方法で指定できます: ディレクトリ（ ``theme.conf`` とその他の必要なファイルを含む）か、同じ内容の zip ファイルのいずれか、です。

ということで、ここでは HTML テーマ を zip ファイルにまとめる方法を紹介したいと思います。

ちょっと復習

さて、自作の HTML テーマということですが、どうやって作ればいいのか分からない方向けの説明も兼ねて、ちょっと復習してみましょう。実際にここに示すように作ってみて、動作確認をすると理解が進むと思うので環境が用意できる方は、手を動かしながら読んでいくと良いと思います。
もちろん、既にご存知の方はこの節は読み飛ばして頂いて結構です。

まず、Sphinx の HTML テーマは以下のような構成になっています。


  + theme.conf
  + template ファイル (例えば layout.html など。必要な場合のみ)
  + static/
      + CSS ファイル
      + 画像ファイル (必要な場合のみ)

このうち、絶対に必要なものは一番上にある theme.conf だけです。その下にある layout.html や CSS ファイルは変更を加える必要がないときには、テーマに含める必要はありません。

ここで仮に mytheme というテーマを作成すると仮定して、構成を見てみることにします。適当なワーキングディレクトリに mytheme というディレクトリを作成し、その下に theme.conf を作成してみましょう :

$ mkdir mytheme
$ cd mytheme
$ vim theme.conf

theme.conf の中身は次のようにします。

[theme]
inherit = sphinxdoc
stylesheet = mytheme.conf
pygments_style = friendly

次に static ディレクトリを作成して、その下に mytheme.css を作成します :

$ mkdir static
$ cd static
$ vim mytheme.css

mytheme.css の中身は次のようにします。変更したスタイルが適用されていることが確認しやすいように、背景色だけ変更しておきましょう :

@import url("sphinxdoc.css");

body {
    background-color: #dbd0e6;
}

ここまでで mytheme ディレクトリの下は次のような構成になっているはずです :

mytheme
  + theme.conf
  + static
      + mytheme.css

そうしたら mytheme ディレクトリの直下に戻って、次の手順で zip ファイルを作成してみましょう :

$ zip -r mytheme.zip *
$ ls -F
mytheme.zip static/     theme.conf

zip ファイルができあがりましたね。そうしたら作成したテーマを適用したい Sphinx のドキュメントプロジェクトディレクトリの中で conf.py と同じディレクトリに mytheme.zip を置き、 conf.py を次のように編集します :

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'mytheme'

# Add any paths that contain custom themes here, relative to this directory.
html_theme_path = ["."]

ポイントとして html_theme_path の値は conf.py からの相対パスを指定します。コメント部分にも書いてありますが、注意しましょう。

あとはいつものとおり、 make html を叩くだけです。

どうでしょう、背景色が薄紫色に変わった sphinxdoc テーマのページが表示されたでしょうか？上手く表示できたら成功です。
逆に make html を実行した後にエラーメッセージが出てしまっている場合は、テーマがうまく読み込めていない可能性があります。この記事のコードスニペット部分と手元のコードをよく見比べてみてください（そしてもしタイポを発見した場合にはコメントをして頂けると助かります）。

おわりに

Sphinx HTML テーマは、ご覧頂いたような手順で簡単に継承・上書きして、配布することができます。しかも HTML テーマのカスタマイズに関して言えば、大掛かりな構造の変更でない限りは Python の知識が無くてもなんとかなります*1。

もし自作のテーマを手元に抱えたままにしているのであれば、この方法を使って他の人にも配ってみてください。

明日は @kashew_nuts さんです。よろしくお願いします。

参考

*1:もちろん、Sphinx が吐く HTML は御世辞にもキレイとは言えないのと、継承元のテーマで適用しているスタイルとの兼ね合いがあるので意図した通りにスタイルを変更するのはなかなか難しいかも知れませんが、そこは Try and Error で慣れていく必要がある部分だと思っています。