reSTソースファイルは様々な拡張子を持つことができます。 .txt を好む人もいれば、 .rst が好きな人もいます。この拡張子は source_suffix で設定することができます。またOSごとにパス区切り文字が変わりますが、Sphinxはこれを抽象化しています。全 “ドキュメント名” は :term: ソースディレクトリ からの相対的な名前として扱われます。また、拡張子は取り除かれます。パス区切り文字もスラッシュ(/)に置き換えられます。パラメータ、このような “文章” を参照するものは、このようなドキュメント名を期待しています。
ドキュメント名のサンプルは、 index, library/zipfile, reference/datamodel/types のようになります。 先頭のスラッシュは不要です。
Restにはドキュメント間の連携をサポートする機能はありませんし、結果のドキュメントを複数の出力ファイルに出すこともできません。 Sphinxは、目次など、ドキュメントを構成するファイル群の関係を追加するカスタムディレクティブを使用します。 toctree ディレクティブはその中でも一番中心的なものになります。
このディレクティブは”目次のツリー”を現在の場所に挿入します。目次の生成には、ディレクティブ本体で指定された関連ドキュメントの中の個別の目次(“サブ目次ツリー”も含む)も使用されます。 maxdepth オプションの数値を設定すると、ツリーの深さを設定することができます。デフォルトではすべての階層を含むツリーが作成されます。 [1]
このサンプルを見てください。このサンプルはPythonドキュメントのライブラリリファレンスからの引用です:
.. toctree::
:maxdepth: 2
intro
strings
datatypes
numeric
(実際はさらに数多くのドキュメントがリストされています)
このディレクティブは二つのことを行っています。
toctree の中のドキュメントのタイトルは、参照先のドキュメントのタイトル情報を自動的に読み込んで使用します。もしこの動作が望ましくなければ、reSTのハイパーリンクに似た文法(Sphinxの cross-referencing syntax)を使って明示的に指定することができます。サンプルを示します:
.. toctree::
intro
文字列のすべて <strings>
datatypes
上記のサンプルの2行目は strings``ドキュメントへのリンクになります。デフォルトの動作では ``strings ドキュメントのタイトルが使用されますが、ここでは”文字列のすべて”という文字列がタイトルとして使用されます。
また、ドキュメント名の代わりに、HTTPのURLを指定することで外部へのリンクを追加することもできます。
もし、セクション番号をHTML出力に追加したい場合には、 numbered フラグオプションをtoctreeに追加します:
.. toctree::
:numbered:
foo
bar
ナンバリングは foo の見出しから開始されます。サブの目次のツリーに対しても自動的にナンバリングされています。サブの文章のtoctreeには numbered フラグが設定されていなくても自動的に処理が行われます。
もしもドキュメントのタイトルだけをツリーに表示して、同じレベルの他の見出しを表示したくない場合には、 titlesonly オプションを使用します:
.. toctree::
:titlesonly:
foo
bar
toctreeディレクティブでは、 glob フラグオプションを指定することで、”GLOB”というものを使用することもできます。使用可能なドキュメントのうち、マッチするエントリーをすべて、アルファベット順に挿入します:
.. toctree::
:glob:
intro*
recipe/*
*
このディレクティブの先頭では、名前が intro で始まるすべてのドキュメントが挿入されます。その次には、 recipe フォルダの中の全てのドキュメントが挿入されます。最後に、一度も挿入されていない、残ったドキュメントが挿入されます。 [2]
self は特別なエントリー名として扱われます。toctreeディレクティブを含むドキュメント自身を表します。これは、toctreeを使用して、”サイトマップ”を作成したい場合に便利です。
hidden オプションというものをディレクティブに設定することもできます:
.. toctree::
:hidden:
doc_1
doc_2
このtoctreeのサンプルは、ドキュメントの階層構造をSphinxに教えますが、このディレクティブがある場所にはドキュメントのリンクは作成されません。これにより、違う形式で出力したり、サイドバーに入れたり、これらのリンクを自分で挿入したい場合にも、きちんとした構造を作ることができます。
最後になりますが ソースディレクトリ (サブディレクトリも含む)の中のドキュメントは、いずれかの toctree ディレクティブの中にリストアップされなければいけません。ソースフォルダには置いてあるが、リストアップされていないファイルがあると、通常のナビゲーションではそのファイルに到達できないということになるため、Sphinxは警告を出力します。 unused_documents を使って明示することで、ビルド対象からドキュメントを外すこともできます。また、 exclude_dirs を使うと、ディレクトリごと対象から外すこともできます。
“マスタードキュメント” (master_doc で指定します)は目次ツリー階層の”ルート”のドキュメントになります。これはドキュメントのメインページとして使うことができます。あるいは、``maxdepth``オプションを指定しない、完全な目次を作成することもできます。
バージョン 0.3 で変更: “glob”オプションが追加されました
バージョン 0.6 で変更: “numbered”と”hidden”オプション、外部リンクのサポート、”self”参照が追加されました。
バージョン 1.0 で変更: “titlesonly” オプションが追加されました。
Sphinxはいくつかのドキュメント名を、自分で使用するために予約済みとしています。これらの名前を持つドキュメントを作ろうとしてはいけません。問題が発生することになります。
以下の名前(もしくはこれらから作られるページ名)が特別なドキュメント名です:
genindex, modindex, search
これらの名前は、それぞれ、全体のインデックス、モジュールインデックス、検索ページを作成するのに使用されます。
全体のインデックスはモジュールに含まれるのエントリーから作られます。すべてのインデックスを生成する 説明ユニット と、 index ディレクティブが利用されます。
モジュールインデックスには module ディレクティブで指定されたエントリーが含まれます。
検索ページは、ビルドされた文章から生成されたJSONの検索インデックスと、JavaScriptを利用した全文検索を行うフォームを含みます。検索は現代的なJavaScriptをサポートする、主要なブラウザで動作するはずです。
_ で始まるすべての名前
Sphinx内ではまだそれほど使用されていませんが、このような名前のドキュメントや、ドキュメントを含むディレクトリは作らないでください。 _ をカスタムテンプレートを入れるディレクトリのプリフィックスに使用することはできます。
脚注
| [1] | maxdepth オプションはLaTeXの出力では適用できません。常に、完全な目次がドキュメントの先頭に挿入されます。このときの深さは tocdpeth カウンタを使って制御することができます。この値をリセットするには latex_preamble コンフィグを使用して、以下のように設定します。 \setcounter{tocdepth}{2} |
| [2] | “GLOB”文法に関する追加説明: 標準のシェル構文で使用できる *, ?, [...], [!...] が使用できます。これらはスラッシュ(/)にはマッチしません。 ** を使用すると、スラッシュ(/)も 含む すべての文字列に対してマッチします。 |