開始使用¶
Sphinx 是一個文件產生器，或是一個工具，可將一組純文字來源檔案翻譯成各種輸出格式，自動產生交叉參考、索引等。也就是說，如果您有一個目錄包含一堆 reStructuredText 或 Markdown 文件，Sphinx 可以產生一系列 HTML 檔案、PDF 檔案（透過 LaTeX）、man page 和更多格式。
Sphinx 專注於文件，特別是手寫文件，然而，Sphinx 也可用於產生部落格、首頁，甚至是書籍。Sphinx 的大部分能力來自於其預設純文字標記格式 reStructuredText 的豐富性，以及其 顯著的擴充能力。
本文檔的目標是讓您快速體驗 Sphinx 是什麼以及您可能如何使用它。當您完成此處的操作後，您可以查看安裝指南，然後是 Sphinx 使用的預設標記格式 reStructuredText 的簡介。
如需撰寫文件的通用「簡介」 – 原因和方法，另請參閱 Eric Holscher 撰寫的 Write the docs。
設定文件來源¶
Sphinx 純文字文件來源集合的根目錄稱為來源目錄。此目錄還包含 Sphinx 設定檔 conf.py，您可以在其中設定 Sphinx 如何讀取您的來源並建置文件的所有方面。[1]
Sphinx 隨附一個名為 sphinx-quickstart 的指令稿，它會設定來源目錄並建立一個預設的 conf.py，其中包含它向您詢問的幾個問題中最有用的設定值。若要使用此功能，請執行
$ sphinx-quickstart
定義文件結構¶
假設您已執行 sphinx-quickstart。它建立了一個包含 conf.py 和根文件 index.rst 的來源目錄。根文件的主要功能是作為歡迎頁面，並包含「目錄樹」（或 toctree）的根。這是 Sphinx 新增到 reStructuredText 的主要功能之一，一種將多個檔案連接到單一文件階層結構的方法。
reStructuredText 指令
toctree 是一個 reStructuredText 指令，這是一種非常通用的標記片段。指令可以有引數、選項和內容。
引數直接在指令名稱後面的雙冒號後給定。每個指令決定它是否可以有引數以及有多少個引數。
選項在引數之後給定，以「欄位列表」的形式。 maxdepth 是 toctree 指令的其中一個選項。
內容在空白行之後跟在選項或引數之後。每個指令決定是否允許內容，以及如何處理內容。
指令的一個常見陷阱是內容的第一行必須縮排到與選項相同的層級。
toctree 指令最初是空的，看起來像這樣
.. toctree::
:maxdepth: 2
您可以在指令的內容中列出文件來新增文件
.. toctree::
:maxdepth: 2
usage/installation
usage/quickstart
...
這正是此文件的 toctree 的外觀。要包含的文件以文件名稱給定，簡而言之，這表示您省略檔案名稱副檔名並使用正斜線 (/) 作為目錄分隔符號。
另請參閱
閱讀更多關於 toctree 指令 的資訊。
您現在可以建立您在 toctree 中列出的檔案並新增內容，它們的節標題將被插入（直到 maxdepth 層級）在 toctree 指令放置的位置。此外，Sphinx 現在知道您的文件的順序和階層結構。（它們可能包含 toctree 指令本身，這表示如果需要，您可以建立深度巢狀階層結構。）
新增內容¶
在 Sphinx 來源檔案中，您可以使用標準 reStructuredText 的大多數功能。Sphinx 還新增了幾個功能。例如，您可以使用 ref 角色以可攜式方式（適用於所有輸出類型）新增跨檔案參考。
例如，如果您正在檢視 HTML 版本，您可以查看本文檔的原始碼 – 使用側邊欄中的「顯示原始碼」連結。
另請參閱
reStructuredText 以取得更深入的 reStructuredText 介紹，包括 Sphinx 新增的標記。
執行建置¶
現在您已新增了一些檔案和內容，讓我們首次建置文件。建置是使用 sphinx-build 程式啟動的
$ sphinx-build -M html sourcedir outputdir
其中 sourcedir 是來源目錄，而 outputdir 是您要放置已建置文件的目錄。-M 選項選擇建置器；在此範例中，Sphinx 將建置 HTML 檔案。
另請參閱
請參閱 sphinx-build man page 以取得 sphinx-build 支援的所有選項。
您也可以建置文件的即時版本，您可以在瀏覽器中預覽。它將偵測變更並在您進行編輯時重新載入頁面。若要執行此操作，請使用 sphinx-autobuild 執行以下命令
$ sphinx-autobuild source-dir output-dir
但是，sphinx-quickstart 指令稿會建立 Makefile 和 make.bat，讓您的生活更輕鬆。這些可以透過執行 make 以及建置器的名稱來執行。例如。
$ make html
這將在您選擇的建置目錄中建置 HTML 文件。執行不帶引數的 make 以查看哪些目標可用。
我該如何產生 PDF 文件？
make latexpdf 執行 LaTeX 建置器，並隨時為您調用 pdfTeX 工具鏈。
文件化物件¶
Sphinx 的主要目標之一是輕鬆文件化任何領域中的物件（以非常廣義的含義）。領域是物件類型的集合，它們屬於一起，並附帶標記來建立和參考這些物件的描述。
最突出的領域是 Python 領域。例如，若要文件化 Python 的內建函式 enumerate()，您會將其新增到您的來源檔案之一。
.. py:function:: enumerate(sequence[, start=0])
Return an iterator that yields tuples of an index and an item of the
*sequence*. (And so on.)
這會像這樣呈現
- enumerate(sequence[, start=0])¶
傳回一個迭代器，該迭代器產生索引和 sequence 項目的元組。（等等。）
指令的引數是您描述的物件的簽名，內容是其文件。可以給定多個簽名，每個簽名都在其自己的行中。
Python 領域也恰好是預設領域，因此您不需要在標記前加上領域名稱。
.. function:: enumerate(sequence[, start=0])
...
如果您保持預設領域的預設設定，則執行相同的工作。
還有幾個指令可用於文件化其他類型的 Python 物件，例如 py:class 或 py:method。每個物件類型也都有一個交叉參考角色。此標記將建立一個連結到 enumerate() 的文件。
The :py:func:`enumerate` function can be used for ...
這是證明：連結到 enumerate()。
同樣，如果 Python 領域是預設領域，則可以省略 py:。哪個檔案包含 enumerate() 的實際文件並不重要；Sphinx 將會找到它並建立一個連結到它。
每個領域都會有關於簽名外觀的特殊規則，並使格式化的輸出看起來漂亮，或新增特定功能，例如連結到參數類型，例如在 C/C++ 領域中。
另請參閱
領域 適用於所有可用的領域及其指令/角色。
基本設定¶
稍早我們提到 conf.py 檔案控制 Sphinx 如何處理您的文件。在該檔案中，該檔案作為 Python 來源檔案執行，您指派設定值。對於進階使用者：由於它由 Sphinx 執行，因此您可以在其中執行非簡單的任務，例如擴充 sys.path 或匯入模組以找出您正在文件化的版本。
您可能想要變更的設定值已由 sphinx-quickstart 放入 conf.py 中，並且最初被註解掉（使用標準 Python 語法：# 註解掉該行的其餘部分）。若要變更預設值，請移除井字號並修改該值。若要客製化未由 sphinx-quickstart 自動新增的設定值，只需新增額外的指派即可。
請記住，該檔案對字串、數字、列表等使用 Python 語法。該檔案預設以 UTF-8 儲存，如第一行中的編碼宣告所示。
另請參閱
設定 以取得所有可用設定值的說明文件。
Autodoc¶
在文件化 Python 程式碼時，通常會將大量文件放在來源檔案中，以文件字串的形式。Sphinx 支援包含來自您模組的文件字串，透過一個名為 autodoc 的擴充功能（擴充功能是一個 Python 模組，為 Sphinx 專案提供額外功能）。
另請參閱
sphinx.ext.autodoc 以取得 autodoc 功能的完整描述。
Intersphinx¶
許多 Sphinx 文件，包括 Python 文件，都發布在網際網路上。當您想要從您的文件連結到這類文件時，您可以使用 sphinx.ext.intersphinx。
為了使用 intersphinx，您需要在 conf.py 中啟用它，方法是將字串 'sphinx.ext.intersphinx' 放入 extensions 列表，並設定 intersphinx_mapping 設定值。
例如，若要連結到 Python 程式庫手冊中的 io.open()，您需要設定您的 intersphinx_mapping 像這樣
intersphinx_mapping = {'python': ('https://docs.python.org/3', None)}
現在，您可以撰寫像 :py:func:`io.open` 這樣的交叉參考。任何在目前文件集中沒有相符目標的交叉參考，都將在 intersphinx_mapping 中設定的文件集中查閱（這需要存取 URL 才能下載有效目標的列表）。Intersphinx 也適用於某些其他領域的角色，包括 :ref:，但是它不適用於 :doc:，因為它是非領域角色。
另請參閱
sphinx.ext.intersphinx 以取得 intersphinx 功能的完整描述。
更多主題待涵蓋¶
腳註