読者です 読者をやめる 読者になる 読者になる

CUBE SUGAR CONTAINER

技術系のこと書きます。

Sphinx: 既存のテーマをカスタマイズする

Sphinx はドキュメントのコンテンツとデザインが分離されている。 デザインを変えたいときはテーマを変更すれば良い。 ただ、既存のテーマそのままでは満足できる見栄えにならないときもある。 そんなときは既存のテーマをカスタマイズする必要が出てくる。 今回はそのやり方について書く。

環境には Mac OS X を使っている。

$ sw_vers                               
ProductName:    Mac OS X
ProductVersion: 10.11.2
BuildVersion:   15C50

下準備

まずは下準備として Sphinx をインストールする。

$ pip install sphinx

次に sphinx-quickstart コマンドを使ってドキュメントを用意する。 デフォルトの入力値から変更しているところだけ示す。

$ sphinx-quickstart
> Separate source and build directories (y/n) [n]: y
> Project name: helloworld
> Author name(s): momijiame
> Project version: 0.1.0
> Project language [en]: ja
> Create Windows command file? (y/n) [y]: n

初期状態ではこんな感じになっている。

$ tree
.
├── Makefile
├── build
└── source
    ├── _static
    ├── _templates
    ├── conf.py
    └── index.rst

4 directories, 3 files

ちなみに tree コマンドは Mac OS X には最初から入っていないので Homebrew で別途入れる。

$ brew install tree

新しくテーマを作る

これから mytheme という名前で新しいテーマを作っていく。 一足先に conf.py にこれから作るテーマの設定を入れてしまおう。

$ sed -i -e "
    s:^#html_theme_path.*$:html_theme_path = ['.']:
    s:^html_theme .*$:html_theme = 'mytheme':
" source/conf.py

蛇足になるけど Mac OS X のデフォルトの sed は GNU sed とはオプションが異なる。 Homebrew で GNU sed を入れた上でエイリアスを張っておくと良い。

$ brew install gnu-sed
$ alias sed="gsed"

新しく作るテーマ用のディレクトリをドキュメントのソースコードが入っているディレクトリの中に用意する。

$ mkdir source/mytheme

テーマの設定ファイルとなる theme.conf を作る。 ここでは epub テーマを継承して新しいテーマを作っていくことにする。 theme セクションの inherit に継承元となるテーマ名を指定しよう。 次に stylesheet はテーマで使用するスタイルシートの名前を指定する。 今回はひとまず継承元のテーマで使われているものをそのまま使おう。 pygments_style はシンタックスハイライトに使われるスタイルを指定できる。 ここもひとまず sphinx を指定しておけば問題ないようだ。

$ cat << 'EOF' > source/mytheme/theme.conf
[theme]
inherit = epub
stylesheet = epub.css
pygments_style = sphinx
EOF

次にドキュメントのレイアウトを決める layout.html を作る。 これはテンプレートエンジンの Jinja2 で処理されることになる。 テンプレートの先頭にある extends では、継承元のテンプレートを指定している。 継承元のテンプレートはテーマ名とドキュメント名をスラッシュで区切る形で指定できる。 その次では、新たに header という名前のブロックを作成して、そこに div 要素を定義している。 これは元々のテンプレートに追加されることになる。

$ cat << 'EOF' > source/mytheme/layout.html
{% extends 'epub/layout.html' %}

{%- block header %}
<div id="header">
    <p>My Header</p>
</div>
{%- endblock header %}
EOF

この状態でドキュメントをビルドしてみよう。

$ make html

できたドキュメントをブラウザで開く。

$ open build/html/index.html

すると、次のように My Header という表示が追加されたドキュメントが表示された。 それ以外は通常の epub テーマと同じ見栄えだ。

f:id:momijiame:20160106122143p:plain

スタイルシートを追加してみる

次は先ほどの内容に適用するスタイルシートを追加してみよう。

まずはスタイルシートを格納するためのディレクトリをテーマ内に static という名前で用意する。

$ mkdir source/mytheme/static

次に、適用したいスタイルシートをそこに追加する。 内容は id: header の背景に色をつけるというもの。

$ cat << 'EOF' > source/mytheme/static/custom.css
#header {
  background-color: #a2e8fe;
}
EOF

そして、先ほどの layout.html をに少し手を加えよう。 今度は extrahead ブロックを定義している。 このブロックは基本的にどのテーマでも用意されている。 スタイルシートやスクリプトを追加する際には、このブロックを拡張することが推奨されているようだ。 そこで、ここに link タグを追加して先ほどのスタイルシートを読み込むようにする。 スタイルシートのパスは pathto() 関数を使って取得する。 先ほど作った static ディレクトリの内容は _static ディレクトリにコピーされるようなので、関数にはそのパスを指定する。

$ cat << 'EOF' > source/mytheme/layout.html
{% extends 'epub/layout.html' %}

{%- block extrahead %}
<link rel="stylesheet" href="{{ pathto('_static/custom.css', 1) }}" type="text/css" />
{%- endblock extrahead %}

{%- block header %}
<div id="header">
    <p>My Header</p>
</div>
{%- endblock header %}
EOF

準備ができたのでドキュメントをビルドし直して内容を確認しよう。

$ make html
$ open build/html/index.html

上手く id: header の背景に色がついた。 f:id:momijiame:20160106122717p:plain

ちなみにテーマで定義されているブロックは次のドキュメントに書かれていた。 http://sphinx.shibu.jp/templating.html

また、継承元のブロックに定義されている内容は super() 関数で取得できるようだ。 つまり、テンプレートの中で得るには {{ super() }} のようにする。

いじょう。