Sphinxでページ内リンク（ページ内の目次）を作る

随分前にSphinxの記事を書きましたが、しばらく使っていなかったのでディレクティブの書き方を忘れていました。先週、社内で使う文書を作ろうと思って、再び quick-start から始めたので少し思い出しました。今日は、HTMLではページ内リンクとして捉えていたものを使ってみた結果を記事にします。

Sphinxでは toctreeを書けば、各パラグラフへのリンクは自動で生成されます。目次のリンクをクリックすると、そのページの段落始まりまでジャンプします。しかし、あるページの内容が多い時（ページが長くなってしまった時）は上部に目次を置いて、ページ内でジャンプさせたいと思うこともあります。そういえばページ内で目次を作れたはずだと思い出し、Sphinx 1.1 documentationの「ディレクティブ」を探したところ、「contents （現在のファイル内だけの目次）」を見つけて、英語の解説ページを開きました。

目次を入れたいページの画像です。
reStructuredText Directives "Table of Contents"

赤丸を付けた小題だけを目次にしたいと思い、ひとまず一行だけ追加して make html しました。

.. contents::

結果はこちら。

やりたいことが三つ。

1. 一番上にある大きなタイトルは目次には不要なので削除したい
2. 「Contents」を「目次」に変える
3. 小題のサブにあたる「手順」は表示されなくて良い

contentsの解説をじっと読んでみると、オプションに toctreeと同じ depthがあります。これを指定することで、「手順」の非表示はできそうです。大きなタイトルを省くには、local というオプションが使えそうです。「目次」を表示させるには、Table of Contentsの名称を設定すれば良いようです。試してみましょう。

.. contents:: 目次
   :local:
   :depth: 1

結果はこちら。

使ったオプションの解説を一部書いておきます。
depth: 目次に表示したいセクションのレベルを整数で指定する。数字がない場合は、指定なし。
local: 空で良い。ディレクティブで書かれたサブセクションのみを目次として表示する。

次回からページ内の目次はすいすい書けそうです。