contents¶ReSTにはドキュメント間の連携をサポートする機能はありませんし、結果のドキュメントを複数の出力ファイルに出すこともできません。Sphinxは、目次など、ドキュメントを構成するファイル群の関係を追加するカスタムディレクティブを使用します。ディレクティブはその中でも一番中心的なものになります。ディレクティブを使えます。toctree::¶このディレクティブは"目次のツリー"を現在の場所に挿入します。目次の生成には、ディレクティブ本体で指定された関連ドキュメントの中の個別の目次("サブ目次ツリー"も含む)も使用されます。始まらない)相対的なドキュメント名が指定された場合は現在のドキュメントからの相対パスとして、絶対的なドキュメント名が指定された場合はソースディレクトリからの相対パスとして、それぞれ取り扱われます。オプションの数値を設定すると、ツリーの深さを設定できます。デフォルトではすべての階層を含むツリーが作成されます。1このサンプルを見てください。here)このディレクティブは二つのことを行っています。stringsなど)の項目も取り込んで目次を作成しています。最大の深さは2に指定されています。関連するドキュメントからトップの1階層分の項目を取得してきて目次に挿入しています。ディレクティブがあればそれも利用されます。いう順番を持っていて、これらのファイルがライブラリインデックスの子供であるという情報を収集します。chapter"というリンクが作成されます。中のドキュメントのタイトルは、参照先のドキュメントのタイトル情報を自動的に読み込んで使用します。syntax)を使って明示的に指定できます。ドキュメントへのリンクになります。ドキュメントのタイトルが使用されますが、ここでは"文字列のすべて"という文字列がタイトルとして使用されます。ドキュメント名の代わりに、HTTPのURLを指定することで外部へのリンクも追加できます。オプションを指定します。見出しから開始されます。サブの目次のツリーに対しても自動的にナンバリングされています。フラグが設定されていなくても自動的に処理が行われます。特定の深さまでのナンバリングだけを行うこともできます。オプションに対して、数値で深さを指定してください。指定するとtoctreeのキャプションとして表示されます。参照できるターゲットとして使用できます。フラグオプションを指定することで、"GLOB"の使用もできます。始まるすべてのドキュメントが挿入されます。フォルダの中の全てのドキュメントが挿入されます。最後に、一度も挿入されていない、残ったドキュメントが挿入されます。特別なエントリー名として扱われます。toctreeディレクティブを含むドキュメント自身を表します。これは、toctreeを使用して、"サイトマップ"を作成したい場合に便利です。フラグオプションを使うことができます。フラグオプションを使ってファイルの順序を反転するときに有用です。doc_2このtoctreeのサンプルは、ドキュメントの階層構造をSphinxに教えますが、このディレクティブがある場所にはドキュメントのリンクは作成されません。これにより、違う形式で出力したり、サイドバーに入れたり、これらのリンクを自分で挿入したい場合にも、きちんとした構造を作ることができます。他のすべてのTOCツリー内のエントリーを無視出来ます。ディレクティブの中にリストアップされなければいけません。ソースフォルダには置いてあるが、リストアップされていないファイルがあると、通常のナビゲーションではそのファイルに到達できないということになるため、Sphinxは警告を出力します。使って明示することで、ビルド対象からドキュメントを外すこともできます。使用して下さい、toctreeを通じて到達できないことをSphinxへ知らせます。指定します)はTOCツリー階層の"ルート"のドキュメントになります。これはドキュメントのメインページとして使うことができます。オプションを指定しない、完全な目次も作成できます。オプションを追加しました。"hidden"オプションを追加しました。オプションを追加しました。オプションに引数を追加しました。オプションを追加しました。オプションを追加しました。特別なドキュメント名¶Sphinxはいくつかのドキュメント名を、自分で使用するために予約済みとしています。これらの名前を持つドキュメントを作ろうとしてはいけません。問題が発生することになります。searchこれらの名前は、それぞれ、全体のインデックス、モジュールインデックス、検索ページを作成するのに使用されます。全体のインデックスはモジュールに含まれるのエントリーから作られます。ディレクティブが利用されます。ディレクティブで指定されたエントリーが含まれます。検索ページは、ビルドされた文章から生成されたJSONの検索インデックスと、JavaScriptを利用した全文検索を行うフォームを含みます。検索は現代的なJavaScriptをサポートする、主要なブラウザで動作するはずです。始まるすべての名前Sphinx内ではまだそれほど使用されていませんが、このような名前のドキュメントや、ドキュメントを含むディレクトリは作らないでください。カスタムテンプレートを入れるディレクトリのプリフィックスに使用することはできます。警告ファイル名に特殊文字を使うときは気をつけてください。思いがけない挙動を示すことがあります。他の箇所へのリンクが動かなくなる場合があります。使用すると、リソースが見つからなくなる場合があります。特別に重要な情報が少しだけある場合に使用します。APIを使用する際に、ユーザが気をつけなければならないことの説明をする場合などに使うと良いでしょう。このディレクティブの中身には、適切に句読点が付いた、完全な文章を書くべきです。warning::¶noteよりも重要な情報があり、APIを使用する際に、気をつけなければならない警告情報をユーザに伝えるために使用するのに適しています。このディレクティブの中身には、適切に句読点が付いた、完全な文章を書くべきです。このディレクティブを使用する方が良いでしょう。APIに追加された時のプロジェクトのバージョンについて記述するのに使用します。このディレクティブがモジュール全体に対して適用する場合には、モジュールセクションの先頭の、文章が始まる前の位置に置くべきです。最初の引数は必須で、バージョン番号を書く必要があります。説明を書くことができます。parameter.ディレクティブヘッドと説明の間には空行を入れてはいけません。マークアップの中では見た目上つながっているようにしなければなりません。似ていますが、現在説明している機能がいつどのように変化したのか(新しい引数、副作用の変更など)を説明するのに使用します。似ていますが、このディレクティブは、この機能がすでに古くて非推奨になったことを示しています。ディレクティブを使用して作ることができます。ディレクティブはサブセクションの直前のセクションに置かれることが多いです。HTMLアウトプットにおいては、メインのテキストの流れから離されて、箱に囲まれて表示されます。中身は、reSTの定義リストを使用しなければなりません。title¶このディレクティブは、目次に表示されないパラグラフの見出しを作成します。"Footnotes"(もしくは選択された言語で指定されている、同様の言葉)だった場合には、脚注の定義だけが含まれていると見なして、LaTeXライターでは無視されます。この場合は空の見出しだけが作成されます。centered::¶このディレクティブはセンターに置かれた、太字のテキストを作成するのに使用します。この表示専用のディレクティブは古いバージョンからの遺産です。ディレクティブを使い、適切なスタイルを追加してください。hlist::¶このディレクティブは短い文章のリストを含みます。このディレクティブは、水平にも数カラム展開することで、よりコンパクトなリストに変換するか、アイテム間のスペースを小さくします。どちらになるかはビルダー次第です。オプションを使用して、水平のカラム数の設定できます。デフォルトでは2になっています。(Pygmentsに推測させます。supports選択された言語によるハイライトがうまくいかなかった場合(例えば、Pygmentsが"Error"トークンを出す等)には、そのブロックはハイライトされなくなります。オプションをサポートしました。example.pyソースコードのファイルは通常、現在のパスからの相対パスで指定します。開始されているときはトップのソースディレクトリからのパス指定をできます。オプションを指定すると、入力ファイル中のタブを希望の幅に展開できます。設定されているエンコードで保存されているものとして処理されます。latin-1このディレクティブは、ファイル全体ではなく、一部分だけを読み込むこともサポートしています。メソッドに属するコード行だけがドキュメントに挿入されます。20行目から最終行までのコードがインクルードされます。あわせて使うことができます。