Help us understand the problem. What is going on with this article?

Sphinxですべての目次をサイドバーに表示する

More than 5 years have passed since last update.

背景

Sphinx ってデフォルトの動作(テーマ)だとサイドバーに表示される目次って、今見ているページに関連する目次のみで全体の目次は見えなくなってしまいますね。

でも、Sphinx-Users.jp ではサイドバーに表示されている目次ってすべてが表示されていて、いつも同じになっているので、これと同じようなことをしようとしたときのメモです。

なお、Sphinx を使い始めたばかりなので、間違いあれば指摘いただけると嬉しいです!

情報

本家の情報では、どのようにすれば... の 「... すべての全体の目次をサイドバーに表示できますか?」にさらっと書いてあります。

が、これでは自分には理解しきれなかったので、Sphinx-Users.jp のソース を見ました。これから得られた知識をもとにして以下を書いています。

やり方

目次用テンプレートの作成

sphinxプロジェクトのソースディレクトリ(プロジェクト直下かsourceフォルダ配下)に、_templates というディレクトリがあるので、この中に globaltoc.html というのを以下のような感じで作る。

<div id="toc" class="sidebarRow">
<h3><a href="http://docs.sphinx-users.jp/">Sphinxリファレンス</a></h3>

<h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
{%- if sphinx_version[:3] >= '1.2' %}
{{ toctree (maxdepth=2, collapse=False, includehidden=True) }}
{% else %}
{{ toctree(maxdepth=2, collapse=False) }}
{% endif %}
</div>

ポイントは後半の toctree の部分。ここで、collapse=False とすることで、全体の目次が常に表示されるようになる、ということらしい。

htmlのマークアップ部分をあとは好みで記述すれば、自分好みのサイドバーが作れる感じですね。

ちなみに、テンプレート に書いてあるように、Jinja というテンプレートエンジンを使っているとのこと。

また、pathtomaster_doc についてはそれぞれのリンクを参照ください。

conf.py の修正

目次用のテンプレートを作成したら、conf.py に以下のような記述を追加する。

html_sidebars = {
    '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'],
}

記述方法については html_sidebars を参照ください。

Sphinx-Users.jp では、ここにTwitterのハッシュタグを埋込むテンプレートを作って、それを読む込むようにしてありました。

あとは

make html

すればOKです。


以上となります。
変なところあればご指摘ください。

takakiku
記事ははてなブログによせることにしました。 なので、今後は http://kikumoto.hatenablog.com/ でおなしゃす!
Why not register and get more from Qiita?
  1. We will deliver articles that match you
    By following users and tags, you can catch up information on technical fields that you are interested in as a whole
  2. you can read useful information later efficiently
    By "stocking" the articles you like, you can search right away