Sphinx におけるナラティブドキュメンテーション

複数のページにまたがるドキュメンテーションを構造化することについて

sphinx-quickstart によって作成されたファイル index.rstroot document であり、その主な機能は、ウェルカムページの役目を果たすこと、そして「目次ツリー」 (もしくは toctree) のルートを含むこと、です。 Sphinx を使用すると、異なる複数のファイルから一つのプロジェクトを構築することができます。これは、プロジェクトの規模が拡大する場合に役立ちます。

例として、 docs/source/usage.rst を (index.rst と同じディレクトリに) 下記の内容で作成してみましょう:

docs/source/usage.rst
Usage
=====

Installation
------------

To use Lumache, first install it using pip:

.. code-block:: console

   (.venv) $ pip install lumache

この新しいファイルは2つの section 見出しと普通の段落テキスト、そして1つの code-block ディレクティブを持っています。code-block ディレクティブはそのブロックの内容を文法的に適切なシンタックスハイライトを付けてソースコードとしてレンダリングします (この場合、 一般的な console テキストのハイライトになります)。

ドキュメントの構造は、一連の見出しスタイルによって決定されます。それは 「使用法」セクションのための「===」の後に、「インストール」セクションのための「---」を使用することで、あなたが 「使用法」の サブセクション として「インストール」セクションを宣言していることになります。

プロセスを終わらせるために、 あなたが今ちょうど作成したドキュメントを含むように toctree directiveindex.rst の終わりに下記のように追加してみましょう:

docs/source/index.rst
Contents
--------

.. toctree::

   usage

このステップは、そのドキュメントを toctree のルートに挿入します。 そのため今そのドキュメントは、プロジェクトの構造に属するようになっています。今までで、次のように見えるようになっているでしょう:

index
└── usage

make html を実行してHTMLのドキュメンテーションを作成すると、 toctree がハイパーリンクのリストとしてレンダリングされることがわかります。これにより、作成したばかりの新しいページにナビゲートできるようになりました。整っていますね!

警告

toctree の外にあるドキュメントは、ビルドプロセス中に WARNING: document isn't included in any toctree というメッセージになり、ユーザーには手の届かないものとなります。

クロスリファレンスを追加することについて

Sphinxの強力な機能の1つは、ドキュメンテーションの特定の部分: ドキュメント、セクション、図、コードオブジェクトなど に :ref:`cross-references <xref-syntax>`をシームレスに追加できる能力です。このチュートリアルはそれらでいっぱいです!

クロスリファレンスを追加するには、 index.rst のイントロダクションの段落の直後に次の文を書きます:

docs/source/index.rst
Check out the :doc:`usage` section for further information.

あなたが使用した doc role<rst-roles-alt>`は、プロジェクト内の特定のドキュメント、この場合は前に作成した ``usage.rst` を自動的に参照します。

または、プロジェクトの任意の部分にクロスリファレンスを追加することもできます。そのためには、 ref ロールを使用し、 a target として機能する明示的な ラベル を追加する必要があります。

たとえば、「インストール」サブセクションを参照するには、次のように、見出しの直前にラベルを追加します:

docs/source/usage.rst
Usage
=====

.. _installation:

Installation
------------

...

そして、 あなたが index.rst に追加した文を次のようにします:

docs/source/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 ドキュメンテーション でハイパーリンクとしてレンダリングされます。

documenting code objects in Sphinx のコードオブジェクトのドキュメント化についてはどうですか?読んでみてください。