ドキュメンテーションツール Sphinx のテーマを作成し PyPI に公開しました。

PyCon mini Sapporo の Lightning Talk で紹介したものですが、当時はパッケージ化していない状態でしたので、このたび公開しました。

インストール方法

README の通りですが、pip インストール可能です。

pip install sphinx_theme_pd

pip インストールした後、Sphinx の conf.py を以下のとおり書き換えてください。

import sphinx_theme_pd
html_theme = "sphinx_theme_pd"
html_theme_path = [sphinx_theme_pd.get_html_theme_path()]

import 文は追加し、 html_theme 及び html_theme_path はコメントアウトされた状態で記述があるので、コメントアウトを外し上記の値を設定します。(これがスタンダードなやり方でしたっけ?)

どんなテーマか

Material Design(風)のレスポンシブ(っぽい)テーマです。

スクリーンショットを置いておきます。

sphinx_theme_pd_1

sphinx_theme_pd_2

sphinx_theme_pd_3

sphinx_theme_pd_4

なお、レイアウトの設定が行き届いていない可能性が充分に(というか間違いなく)あります。プレーンで表示されたりレイアウト崩れがある場合は issue に上げてもらうか pull-req もお待ちしております。

技術的なこと

テンプレートは basic を継承しています。当初スクラッチで書くつもりでしたが、Sphinx がはき出すHTMLタグ(リストとか、コードブロック)を書き換えるのが容易ではなかったので、大部分 basic に委ねることにしました。

CSS は Sass で書いています。Sass のファイル群もGithubに置いてあります。ただし未整理なので綺麗な Sass ではありません。(Sass を使うとネスト地獄や置換地獄から解放されますが、 Sass 使ったからといって綺麗なソースになるわけではないですね、ということを痛感。ピュアなCSSよりはましですが)

一部 jQuery で HTML を書き換えています。スマートな方法ではないと思いますが取り敢えずの落としどころとして。。

謝辞

以下のドキュメントにお世話になりました。

グリッドレイアウトに以下のCSSセットを利用しています。

また、いくつかの質問に回答いただいた @shimizukawa さん、ありがとうございました!