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
這個新檔案包含兩個 章節 標題、一般的段落文字，以及一個 code-block 指令，它將內容區塊呈現為原始碼，並具有適當的語法高亮度顯示（在本例中為通用的 console 文字）。
文件的結構是由標題樣式的順序決定的，這表示，透過在「Usage」章節的 === 之後使用 --- 作為「Installation」章節，您已宣告「Installation」是「Usage」的子章節。
為了完成這個過程，在 index.rst 的結尾新增一個 toctree 指令，包含您剛建立的文件，如下所示
Contents
--------
.. toctree::
usage
這個步驟將該文件插入 toctree 的根目錄，所以現在它屬於您的專案結構，到目前為止看起來像這樣
index
└── usage
如果您執行 make html 建置 HTML 文件，您將看到 toctree 被呈現為超連結列表，這讓您可以導覽到您剛建立的新頁面。很棒吧！
警告
toctree 之外的文件將導致建置過程中出現 WARNING: document isn't included in any toctree 訊息，並且使用者無法存取。
新增交叉參照¶
Sphinx 的一個強大功能是能夠無縫地新增交叉參照到文件的特定部分：文件、章節、圖形、程式碼物件等等。本教學充滿了這些參照！
若要新增交叉參照，請在 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 中文件化程式碼物件呢？繼續閱讀！