Sphinxでテーマをカスタマイズしたときの備忘録

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」になっていてわかりにくいので、プロジェクト名を表示するように変更します。

001

sphinx_rtd_themeのソースコードを見ると、パンくずリストの部分はは「breadcrumbs.html」に記述されていました。

<div role="navigation" aria-label="breadcrumbs navigation">
  <ul class="wy-breadcrumbs">
    <li><a href="{{ pathto(master_doc) }}">Docs</a> &raquo;</li>
      {% for doc in parents %}
          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</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> &raquo;</li>
      {% for doc in parents %}
          <li><a href="{{ doc.link|e }}">{{ doc.title }}</a> &raquo;</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」の文字かプロジェクト名に変更されました。

002

コメントを残す

メールアドレスが公開されることはありません。 が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください