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

Sphinxの検索機能をGoogleカスタム検索に置き換える

Sphinxはクライアント側だけで実行できるJavaScriptで実装された検索機能を持っています。
この検索機能をGoogleカスタム検索に置き換える方法を紹介します。

Googleのカスタム検索のページで、検索エンジンのタグを取得します。

_templatesフォルダーにsearchbox.htmlファイルを作成して、取得した検索エンジンのタグを貼り付けます。

<div id="searchbox">
<h3>検索</h3>
<script>
  (function() {
    var cx = 'XXXXXXXXXXXXXXXXXXXXX:XXXXXXXXXXX';
    var gcse = document.createElement('script');
    gcse.type = 'text/javascript';
    gcse.async = true;
    gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') +
        '//www.google.com/cse/cse.js?cx=' + cx;
    var s = document.getElementsByTagName('script')[0];
    s.parentNode.insertBefore(gcse, s);
  })();
</script>
<gcse:search></gcse:search>
</div>

「make html」を実行して、HTMLファイルを作成します。

以上です。

先日公開した次のエントリーでは、上記の方法で設置したGoogleカスタム検索を使用しています。

Sphinxでサイドバーの検索ボックスを非表示にするには

Sphinxでサイドバーの検索ボックスを非表示にするには、
何も記述しない空のsearchbox.htmlファイルを、_templatesフォルダーに配置します。