Sphinx のドキュメントデザインに Twitter Bootstrap を使う

テンプレートを差し替えてみたら思ったよりもすんなりできたのでメモ。

1. Sphinx でドキュメントを書く。
2. _templates ディレクトリに "layout.html" を置く。(下記)
3. Twitter Bootstrap のサイトから ZIP パッケージをダウンロードする。
4. パッケージを解凍する。
5. _static ディレクトリに "css", "js", "img" をコピーする。
6. make html で HTML をビルドする。
7. ブラウザで表示を確認する。

(テーマは default にしておく)

初版のコード：

	{#
	default/layout.html
	‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
	Sphinx layout template for the default theme.
	:copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
	:license: BSD, see LICENSE for details.
	#}
	{% extends "basic/layout.html" %}
	{% set script_files = script_files + ['_static/js/bootstrap.min.js'] %}
	{% set css_files = css_files + ['_static/css/bootstrap.min.css', '_static/css/bootstrap-responsive.min.css'] %}
	{%- block extrahead %}
	<style type="text/css">
	body {
	padding-top: 60px;
	}
	</style>
	{% endblock %}
	{%- block header %}
	<div class="navbar navbar-fixed-top">
	<div class="navbar-inner">
	<div class="container">
	<a class="brand" href="{{ pathto('index') }}">{{ project|e }}</a>
	<div class="nav-collapse">
	<ul class="nav">
	{%- for parent in parents %}
	<li><a href="{{ parent.link|e }}" {% if loop.last %}{{ accesskey("U") }}{% endif %}>{{ parent.title }}</a></li>
	{%- endfor %}
	</ul>
	<ul class="nav pull-right">
	{%- for rellink in rellinks %}
	<li>
	<a href="{{ pathto(rellink[0]) }}" title="{{ rellink[1]|striptags|e }}"
	{{ accesskey(rellink[2]) }}>{{ rellink[3] }}</a>
	</li>
	{%- endfor %}
	{%- block rootrellink %}{%- endblock %}
	{%- block relbaritems %} {% endblock %}
	{%- if show_source and has_source and sourcename %}
	<li><a href="{{ pathto('_sources/' + sourcename, true)|e }}"
	rel="nofollow">{{ _('Show Source') }}</a></li>
	{%- endif %}
	</ul>
	</div> <!-- /.nav-collapse -->
	</div>
	</div>
	</div>
	{% endblock %}
	{%- block content %}
	<div class="container">
	<div class="row">
	<div class="span12">
	{%- block document %}
	{% block body %} {% endblock %}
	{%- endblock %}
	</div>
	</div> <!-- /.row -->
	</div> <!-- /.container -->
	{% endblock %}
	{%- block footer %}
	<hr>
	<div class="navbar">
	<div class="navbar-inner">
	<div class="container">
	<div class="nav-collapse">
	<ul class="nav pull-right">
	{%- if prev %}
	<li><a href="{{ prev.link|e }}">{{ prev.title }}</a></li>
	{%- endif %}
	<li><a class="uplink" href="{{ pathto(master_doc) }}">{{ _('Contents') }}</a></li>
	{%- if next %}
	<li><a href="{{ next.link|e }}">{{ next.title }}</a></li>
	{%- endif %}
	</ul>
	</div>
	</div>
	</div>
	</div>
	{% endblock %}
	{%- block sidebar1 %}{% endblock %}
	{%- block sidebar2 %}{% endblock %}
	{% block relbar1 %}{% endblock %}
	{% block relbar2 %}{% endblock %}

view raw layout.html hosted with ❤ by GitHub

めも：

• セクションタイトルがナビゲーションバーの右側に表示されてしまう。
• fluid のレイアウトもサポートできると便利そう。
• well とか hero-unit クラスをサポートできると見栄えが整いそう。
• グリフアイコン用の記法みたいなものを定義しておくと、ドキュメントを書いているときに嬉しい。