Sphinxでテーマをカスタマイズしたときの手順を記録しておきます。
Sphinxのバージョンは、執筆時点での最新の「Sphinx 1.4a1」。
sphinx_rtd_themeの導入
Sphinxのテーマには「sphinx_rtd_theme」を使用しました。
sphinx_rtd_themeを使うには、conf.pyを編集します。
import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
HTMLファイルを出力して、テーマが適用されていることを確認します。
make html
テーマのカスタマイズ
パンくずリストの先頭が「Docs」になっていてわかりにくいので、プロジェクト名を表示するように変更します。
sphinx_rtd_themeのソースコードを見ると、パンくずリストの部分はは「breadcrumbs.html」に記述されていました。
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="{{ pathto(master_doc) }}">Docs</a> »</li>
{% for doc in parents %}
<li><a href="{{ doc.link|e }}">{{ doc.title }}</a> »</li>
{% endfor %}
Sphinxのプロジェクトのフォルダーに新しいフォルダーを作成し、フォルダーの名前をテーマ名と同じ名前にします。
├sphinx_rtd_theme/ ←新しいフォルダーを作成する
├_static/
├_templates/
├conf.py
├index.rst
├make.bat
└Makefile
作成したフォルダーにsphinx_rtd_themeの「breadcrumbs.html」をコピーします。
├sphinx_rtd_theme/
│└breadcrumbs.html ←コピーする
├_static/
├_templates/
├conf.py
├index.rst
├make.bat
└Makefile
コピーした「breadcrumbs.html」の「Docs」を「{{ project }}」に変更します。
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="{{ pathto(master_doc) }}">{{ project }}</a> »</li>
{% for doc in parents %}
<li><a href="{{ doc.link|e }}">{{ doc.title }}</a> »</li>
{% endfor %}
<li>{{ title }}</li>
conf.pyを編集し、テーマのファイルを読み込むフォルダーを変更します。」
html_theme_path = ["."]
sphinx_rtd_themeフォルダーにtheme.confを作成します。
theme.confにはテーマの設定を記述します。
├sphinx_rtd_theme/
│├breadcrumbs.html
│└theme.conf ←作成する
├_static/
├_templates/
├conf.py
├index.rst
├make.bat
└Makefile
theme.confに次の行を追加します。
[theme]
inherit = sphinx_rtd_theme
inheritは継承元のテーマを指定します。
HTMLファイルを作成します。
make clean html
作成されたファイルを確認します。
「Docs」の文字かプロジェクト名に変更されました。