Sphinx HTML Theme Hacks

Sphinx
HTML Theme
Hacks @shkumagai
Oct 26, 2014
SphinxCon 2014

@shkumagai
Ad system backend enginner
using Python, Common Lisp, Java, C++...
Sphinx-Users.jp member
Sphinx HTML Theme Author
- sphinxjp.themes.bizstyle
- sphinxjp.themes.dotted
- sphinxjp.themes.impressjs
- sphinxjp.themes.tinkerpress

話すこと
• HTMLテーマとは
• HTMLテーマの構造
• HTMLテーマの作り方
• パッケージングと配布

HTMLテーマとは
• Sphinxで「make html」を実行して出力される
HTMLの見せ方をまとめたもの
• 標準で８種類のテーマがある
• バージョン0.6から導入された機能
• 1.3からはbizstyleも組み込みとして使えます

組込みテーマの使い方
• conf.pyに次のように指定して...
html_theme = "default"
html_theme_options = {
"rightsidebar": "true",
}
• いつものように「make html」するだけ

どう適用されてるか
• conf.pyのhtml_theme変数の値を元に、Sphinxの
パッケージのthemesディレクトリから該当する
テーマのファイル群を取得。
• HTML Builderの初期化のタイミングで、テーマ
を初期化。
• HTML生成時にテーマのテンプレートを使ってド
キュメントを生成。

HTMLテーマの構造
HTML_THEME_PATH/
└ THEME_NAME/
├ theme.conf
├ layout.html
├ 　　:
└ static/
├ THEME_NAME.css
└ THEME_NAME.js

HTML_THEME_PATH
• Sphinx HTMLテーマが配置されているパス
• デフォルトではインストールされたSphinxパッ
ケージの中のthemesディレクトリ
• conf.pyを使って任意のパスを指定可能

theme.conf
• HTMLテーマの全体の構成を定義するファイル
• 他のテーマを継承するか？
• Pygmentsのスタイルは何を使うか？
• 独自オプションは何があるのか？

layout.html
• 実際に表示されるHTMLの元になるテンプレート
の土台
• 記述言語はJinja2
• 別テンプレートを継承したり、マクロを定義し
たりできる
• カスタマイズするとき、ここから読み始めると
よい（個人の感想です）

THEME_NAME.css
• テーマ専用スタイルを定義するスタイルシート
• しかし必須ではない
• 静的テンプレートで値の埋め込みもできる

テーマを作る
• まず、名前を決める。名前重要。
• ここではsphinxcon14という名前のテーマを作っ
てみる。

用意するもの
• theme.conf
• layout.html
• sphinxcon14.css

ファイルの配置
sphinxcon14/
├ theme.conf
├ layout.html
└ static/
└ sphinxcon14.css

theme.conf
• themeとoptionsの2つのセクションで構成されて
いる。
• themeセクションは必須。optionsは任意。
• 事実上、HTMLテーマの核。
• 何は無くともtheme.confだけは書く。

theme.conf
[theme]
inherit = basic
stylesheet = sphinxcon14.css
pygments_style = friendly

layout.html
• doctype, header, footer, relbar, sidebar, content
等のブロックで構成されている。
• ベースのテーマを継承する場合は、継承の宣言
を記述して、変更したい部分だけ上書きしたり、
新規に追加したりする。
• 継承しない場合は、必要なものを全て書く。

layout.html
{% extends "basic/layout.html" %}
{# put the sidebar before the body #}
{% block sidebar1 %}{{ sidebar() }}{% endblock %}
{% block sidebar2 %}{% endblock %}
{# doctype override #}
{%- block doctype %}
<!doctype html>
{%- endblock %}

sphinxcon14.css
• layout.htmlを使って出力されるHTMLに対して
適用するスタイルを記述していく。
• 最初から全部自分で書くよりも、既存のテーマ
の記述を真似て少しずつ変更していく方が手を
つけやすい。

sphinxcon14.css
@import url("basic.css");
body {
font-family: 'Lucida Grande','Geneva',
'Verdana', sans-serif;
font-size: 14px;
letter-spacing: -0.01em;
line-height: 150%;
text-align: center;
background-color: white;
background-image: url(background_b01.png);
color: black;
padding: 0;
margin: 0px 40px 0px 40px;
}
:

ファイルの配置(再掲)
sphinxcon14/
├ theme.conf
├ layout.html
└ static/
└ sphinxcon14.css

実際に使ってみる
project_root/
├ conf.py
├ index.rst
├ sphinxcon14/
│　├ theme.conf
│　├ layout.html
│　└ static/
│　　　└ sphinxcon14.css
├ _build
└ _static

conf.py
html_theme = "sphinxcon14"
html_theme_path = ["."]
• html_themeにはテーマの名前（=ディレクトリ
の名前）を指定する。
• html_theme_pathは任意のパスを指定する。
conf.pyからの相対パスも指定できる。

パッケージングと配布

作った、はいいけれど
• ドキュメントのプロジェクトを作成する度にテー
マのディレクトリをコピーするのはダルい。
• テーマを修正したとき、使っているプロジェク
トすべてにさっと反映したい。
• プロジェクトごとに独自の変更をしてしまって
収集がつかなくなる。

解決方法
• テーマディレクトリの中身をZIPアーカイブする
• テーマをパッケージにする

ZIPアーカイブする
• HTMLテーマのディレクトリ構造の中身を、その
ままZIPでアーカイブ化するだけ（アーカイブに
テーマディレクトリ自身は含めない）。
• ドキュメントプロジェクトへの配置方法は、ディ
レクトリの時と同じ。

ZIPアーカイブする
$ cd sphinxcon14
$ zip -r ../sphinxcon14.zip *
$ unzip -Z sphinxcon14.zip
... layout.html
... static/
... static/sphinxcon14.css
... theme.conf

ZIPアーカイブの利点
• テーマのZIPファイル１つを配布すればテーマの
適用が可能。
• 修正後の再配布も、ディレクトリのまま配布す
るよりは簡単。

パッケージにする
• HTMLテーマを独立した１つのパッケージに仕立
てる。
• テーマをインストールして、conf.pyでテーマを
指定することでドキュメントにテーマを適用す
る。
• 例： sphinxjp.themes.bizstyle

パッケージの利点
• pipやsetuptoolsでインストールできる。
• （実装方法に依存するが）conf.pyの変更箇所が
少なくて済む。
• PyPIに上げれば世界中の人に使ってもらえる機
会が得られる。

• HTML theming support
http://sphinx-doc.org/theming.html
• Templating
http://sphinx-doc.org/templating.html
• The build configuration file
http://sphinx-doc.org/config.html

• sphinxjp.themes.bizstyle
https://bitbucket.org/shkumagai/
sphinxjp.themes.bizstyle
• sphinxjp.themes.dotted
https://github.com/shkumagai/sphinxjp.themes.dotted
• sphinxjp.themes.impressjs
https://github.com/shkumagai/
sphinxjp.themes.impressjs

• Sphinxのテーマを継承して体裁をカスタマイズし
よう
http://heartbeats.jp/hbblog/2013/08/sphinx-customize-theme.html

Sphinx HTML Theme Hacks

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Sphinx HTML Theme Hacks

Similaire à Sphinx HTML Theme Hacks (20)

Sphinx HTML Theme Hacks