TOCツリー

ReSTにはドキュメント間の連携をサポートする機能はありませんし、結果のドキュメントを複数の出力ファイルに出すこともできません。 Sphinxは、目次など、ドキュメントを構成するファイル群の関係を追加するカスタムディレクティブを使用します。 toctree ディレクティブはその中でも一番中心的なものになります。

注釈

単純に一つのファイルを別のファイルに”挿入”する場合、 include ディレクティブを使えます。

.. toctree::

このディレクティブは”目次のツリー”を現在の場所に挿入します。目次の生成には、ディレクティブ本体で指定された関連ドキュメントの中の個別の目次(“サブ目次ツリー”も含む)も使用されます。相対的なドキュメント名(/ で始まらない)が指定されると、。 maxdepth オプションの数値を設定すると、ツリーの深さを設定できます。デフォルトではすべての階層を含むツリーが作成されます。 [1]

このサンプルを見てください。このサンプルはPythonドキュメントのライブラリリファレンスからの引用です:

.. toctree::
   :maxdepth: 2

   intro
   strings
   datatypes
   numeric
   (many more documents listed here)

このディレクティブは二つのことを行っています。

  • ここで指定されたファイル群(intro, stringsなど)の項目も取り込んで目次を作成しています。最大の深さは2に指定されています。つまり、関連するドキュメントからトップの1階層分の項目を取得してきて目次に挿入しています。指定されたファイルに toctree ディレクティブがあればそれも利用されます。

  • Sphinxはこのディレクティブから、関連するドキュメントが intro, strings という順番を持っていて、これらのファイルがライブラリインデックスの子供であるという情報を収集します。これらの情報を使って、”next chapter”, “previous chapter”, “parent chapter”というリンクが作成されます。

エントリー

toctree の中のドキュメントのタイトルは、参照先のドキュメントのタイトル情報を自動的に読み込んで使用します。もしこの動作が望ましくなければ、reSTのハイパーリンクに似た文法(Sphinxの cross-referencing syntax)を使って明示的に指定できます。サンプルを示します:

.. toctree::

   intro
   All about strings <strings>
   datatypes

上記のサンプルの2行目は strings ドキュメントへのリンクになります。デフォルトの動作では strings ドキュメントのタイトルが使用されますが、ここでは”文字列のすべて”という文字列がタイトルとして使用されます。

また、ドキュメント名の代わりに、HTTPのURLを指定することで外部へのリンクも追加できます。

セクションのナンバリング

HTML 出力においてもセクション番号を利用したい場合は、上位の toctree に numbered オプションを指定します。サンプルを示します:

.. toctree::
   :numbered:

   foo
   bar

ナンバリングは foo の見出しから開始されます。サブの目次のツリーに対しても自動的にナンバリングされています。サブの文章のtoctreeには numbered フラグが設定されていなくても自動的に処理が行われます。

特定の深さまでのナンバリングだけを行うこともできます。 numbered オプションに対して、数値で深さを指定してください。

追加のオプション

caption を指定するとtoctreeのキャプションとして表示されます。また、 name オプションを指定すると、 ref で参照できるターゲットとして使用できます。例:

.. toctree::
   :caption: Table of Contents
   :name: mastertoc

   foo

もしもドキュメントのタイトルだけをツリーに表示して、同じレベルの他の見出しを表示したくない場合には、 titlesonly オプションを使用します:

.. toctree::
   :titlesonly:

   foo
   bar

toctreeディレクティブでは、 glob フラグオプションを指定することで、”GLOB”の使用もできます。使用可能なドキュメントのうち、マッチするエントリーをすべて、アルファベット順に挿入します:

.. toctree::
   :glob:

   intro*
   recipe/*
   *

このディレクティブの先頭では、名前が intro で始まるすべてのドキュメントが挿入されます。その次には、 recipe フォルダの中の全てのドキュメントが挿入されます。最後に、一度も挿入されていない、残ったドキュメントが挿入されます。 [2]

self は特別なエントリー名として扱われます。toctreeディレクティブを含むドキュメント自身を表します。これは、toctreeを使用して、”サイトマップ”を作成したい場合に便利です。

You can use the reversed flag option to reverse the order of the entries in the list. This can be useful when using the glob flag option to reverse the ordering of the files. Example:

.. toctree::
   :glob:
   :reversed:

   recipe/*

hidden オプションというものをディレクティブに設定することもできます:

.. toctree::
   :hidden:

   doc_1
   doc_2

このtoctreeのサンプルは、ドキュメントの階層構造をSphinxに教えますが、このディレクティブがある場所にはドキュメントのリンクは作成されません。これにより、違う形式で出力したり、サイドバーに入れたり、これらのリンクを自分で挿入したい場合にも、きちんとした構造を作ることができます。

トップレベルの単一の toctree だけを残して他のより低いレベルの toctree をすべて隠したい場合、トップレベルの toctree エントリに “includehidden” オプションを加えることができます:

.. toctree::
   :includehidden:

   doc_1
   doc_2

hidden オプションで 他のすべてのTOCツリー内のエントリーを無視出来ます。

最後になりますが ソースディレクトリ (サブディレクトリも含む)の中のドキュメントは、いずれかの toctree ディレクティブの中にリストアップされなければいけません。ソースフォルダには置いてあるが、リストアップされていないファイルがあると、通常のナビゲーションではそのファイルに到達できないということになるため、Sphinxは警告を出力します。

exclude_patterns を使って明示することで、ビルド対象からドキュメントを外すこともできます。ドキュメントをビルドさせる場合には the “orphan” metadata を使用して下さい、toctreeを通じて到達できないことをSphinxへ知らせます。

“マスタードキュメント” (master_doc で指定します)はTOCツリー階層の”ルート”のドキュメントになります。これはドキュメントのメインページとして使うことができます。あるいは、 maxdepth オプションを指定しない、完全な目次も作成できます。

バージョン 0.3 で変更: “globbing” オプションを追加しました。

バージョン 0.6 で変更: 外部リンクのサポートと”self”参照と同じように、”numbered” と”hidden”オプションを追加しました。

バージョン 1.0 で変更: “titlesonly” オプションを追加しました。

バージョン 1.1 で変更: “numbered” オプションに引数を追加しました。

バージョン 1.2 で変更: “includehidden” オプションを追加しました。

バージョン 1.3 で変更: “caption” と “name” オプションを追加しました。

特別なドキュメント名

Sphinxはいくつかのドキュメント名を、自分で使用するために予約済みとしています。これらの名前を持つドキュメントを作ろうとしてはいけません。問題が発生することになります。

以下の名前(もしくはこれらから作られるページ名)が特別なドキュメント名です:

  • genindexmodindexsearch

    これらの名前は、それぞれ、全体のインデックス、モジュールインデックス、検索ページを作成するのに使用されます。

    全体のインデックスはモジュールに含まれるのエントリーから作られます。すべてのインデックスを生成する オブジェクト説明 と、 index ディレクティブが利用されます。

    モジュールインデックスには py:module ディレクティブで指定されたエントリーが含まれます。

    検索ページは、ビルドされた文章から生成されたJSONの検索インデックスと、JavaScriptを利用した全文検索を行うフォームを含みます。検索は現代的なJavaScriptをサポートする、主要なブラウザで動作するはずです。

  • _ で始まるすべての名前

    Sphinx内ではまだそれほど使用されていませんが、このような名前のドキュメントや、ドキュメントを含むディレクトリは作らないでください。 _ をカスタムテンプレートを入れるディレクトリのプリフィックスに使用することはできます。

警告

ファイル名に特殊文字を使うときは気をつけてください。思いがけない挙動を示すことがあります。

  • HTMLを使うフォーマットに、コロン : を使わないでください。他の箇所へのリンクが動かなくなる場合があります。

  • ePubフォーマットに、プラス + を使わないでください。使用すると、リソースが見つからなくなる場合があります。

脚注

[1]

LaTeXライターはドキュメントの最初のtoctreeディレクティブの maxdepth オプションのうち、最初のものしか参照しません。

[2]

“GLOB”文法に関する追加説明: 標準のシェル構文で使用できる *, ?, [...], [!...] が使用できます。これらはスラッシュ(/)にはマッチしません。 ** を使用すると、スラッシュ(/)も 含む すべての文字列に対してマッチします。