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 テーマと同じ見栄えだ。
スタイルシートを追加してみる
次は先ほどの内容に適用するスタイルシートを追加してみよう。
まずはスタイルシートを格納するためのディレクトリをテーマ内に 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 の背景に色がついた。
ちなみにテーマで定義されているブロックは次のドキュメントに書かれていた。 http://sphinx.shibu.jp/templating.html
また、継承元のブロックに定義されている内容は super() 関数で取得できるようだ。 つまり、テンプレートの中で得るには {{ super() }} のようにする。
いじょう。
