Sphinxにおけるナラティブドキュメント¶
複数ページにわたるドキュメントの構成¶
sphinx-quickstartによって作成されるファイルindex.rstはルートドキュメントであり、その主な機能は、ようこそページとして機能し、「目次ツリー」（またはtoctree）のルートを含むことです。Sphinxを使用すると、異なるファイルからプロジェクトをアセンブルでき、プロジェクトが成長する際に役立ちます。
例として、新しいファイルdocs/source/usage.rst（index.rstの隣に）を作成し、次の内容を記述します。
Usage
=====
Installation
------------
To use Lumache, first install it using pip:
.. code-block:: console
(.venv) $ pip install lumache
この新しいファイルには、2つのセクションヘッダー、通常の段落テキスト、およびコンテンツのブロックをソースコードとしてレンダリングするcode-blockディレクティブ（この場合は、一般的なconsoleテキスト）が含まれています。
ドキュメントの構造は、見出しスタイルの連続によって決定されます。つまり、「Usage」セクションの===の後で「Installation」セクションに---を使用することで、「Installation」を「Usage」のサブセクションとして宣言しています。
処理を完了するには、作成したドキュメントを含むtoctree ディレクティブをindex.rstの最後に追加します。
Contents
--------
.. toctree::
usage
この手順により、そのドキュメントがtoctreeのルートに挿入されるため、作成したプロジェクトの構造に属するようになります。現在のところ、プロジェクトは次のようになります。
index
└── usage
make htmlを実行してHTMLドキュメントをビルドすると、toctreeがハイパーリンクのリストとしてレンダリングされ、作成した新しいページに移動できます。素晴らしいですね！
警告
toctreeの外にあるドキュメントは、ビルドプロセス中にWARNING: document isn't included in any toctreeというメッセージが表示され、ユーザーがアクセスできなくなります。
相互参照の追加¶
Sphinxの強力な機能の1つは、ドキュメントの特定の部分（ドキュメント、セクション、図、コードオブジェクトなど）への相互参照をシームレスに追加できることです。このチュートリアルには、それがたくさん含まれています！
相互参照を追加するには、index.rstの導入段落の直後に次の文を書きます。
Check out the :doc:`usage` section for further information.
使用したdoc ロールは、プロジェクト内の特定のドキュメント（この場合は、前に作成したusage.rst）を自動的に参照します。
あるいは、プロジェクトの任意の部分への相互参照を追加することもできます。そのためには、refロールを使用し、ターゲットとして機能する明示的なラベルを追加する必要があります。
たとえば、「Installation」サブセクションを参照するには、見出しの直前にラベルを追加します。
Usage
=====
.. _installation:
Installation
------------
...
そして、index.rstに追加した文を次のようにします。
Check out the :doc:`usage` section for further information, including how to
:ref:`install <installation>` the project.
ここで、ちょっとしたコツがあります。install部分はリンクの表示方法を指定します（特定の単語にする必要があるため、文が意味を成します）。一方、<installation>部分は、相互参照を追加する実際のラベルを参照します。明示的なタイトルを含めないで:ref:`installation`を使用すると、セクションタイトル（この場合はInstallation）が使用されます。:doc:と:ref:の両方のロールは、HTMLドキュメントではハイパーリンクとしてレンダリングされます。
Sphinxでのコードオブジェクトの文書化については、読み進めてください！