Sphinx におけるナラティブドキュメンテーション¶
複数のページにまたがるドキュメンテーションを構造化することについて¶
sphinx-quickstart
によって作成されたファイル index.rst
は root document であり、その主な機能は、ウェルカムページの役目を果たすこと、そして「目次ツリー」 (もしくは 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つの section 見出しと普通の段落テキスト、そして1つの code-block
ディレクティブを持っています。code-block
ディレクティブはそのブロックの内容を文法的に適切なシンタックスハイライトを付けてソースコードとしてレンダリングします (この場合、 一般的な console
テキストのハイライトになります)。
ドキュメントの構造は、一連の見出しスタイルによって決定されます。それは 「使用法」セクションのための「===」の後に、「インストール」セクションのための「---」を使用することで、あなたが 「使用法」の サブセクション として「インストール」セクションを宣言していることになります。
プロセスを終わらせるために、 あなたが今ちょうど作成したドキュメントを含むように toctree
directive を 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
のイントロダクションの段落の直後に次の文を書きます:
Check out the :doc:`usage` section for further information.
あなたが使用した doc
role<rst-roles-alt>`は、プロジェクト内の特定のドキュメント、この場合は前に作成した ``usage.rst` を自動的に参照します。
または、プロジェクトの任意の部分にクロスリファレンスを追加することもできます。そのためには、 ref
ロールを使用し、 a target として機能する明示的な ラベル を追加する必要があります。
たとえば、「インストール」サブセクションを参照するには、次のように、見出しの直前にラベルを追加します:
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 ドキュメンテーション でハイパーリンクとしてレンダリングされます。
documenting code objects in Sphinx のコードオブジェクトのドキュメント化についてはどうですか?読んでみてください。