Sphinx API¶
由於許多專案的文件會需要特殊功能，Sphinx 設計為可在多個層級上進行擴充。
以下列出您可以在擴充套件中執行的幾件事
新增 建置器 以支援新的輸出格式或對剖析文件執行的動作。
註冊自訂 reStructuredText 角色和指令，使用 Docutils 標記 API 擴充標記。
在整個建置過程中的策略位置新增自訂程式碼到所謂的「hook 點」，讓您註冊 hook 並執行特定程式碼。例如，請參閱 事件回呼 API。
擴充套件只是一個具有 setup() 函數的 Python 模組。使用者透過將擴充套件的模組名稱（或子模組）放在其 extensions 設定值中來啟用擴充套件。
當執行 sphinx-build 時，Sphinx 會嘗試匯入列出的每個模組，並執行 yourmodule.setup(app)。此函數用於準備擴充套件（例如，透過執行 Python 程式碼）、連結 Sphinx 在建置過程中使用的資源（如 CSS 或 HTML 檔案），以及通知 Sphinx 擴充套件提供的所有內容（例如指令或角色定義）。app 引數是 Sphinx 的執行個體，可讓您控制 Sphinx 建置的大部分方面。
注意
如果設定檔包含 setup() 函數，則設定檔本身可以視為擴充套件。要載入的所有其他擴充套件都必須列在 extensions 設定值中。
本頁的其餘部分描述了開發擴充套件的一些高階層面，以及您可以控制的 Sphinx 行為的各個部分。如需擴充套件如何建置和用於控制 Sphinx 不同部分的範例，請參閱教學課程。
重要物件¶
在撰寫擴充套件時，您將使用其 API 的幾個重要物件。這些是
- 應用程式
應用程式物件（通常稱為
app）是Sphinx的執行個體。它控制大多數高階功能，例如擴充套件的設定、事件分派和產生輸出（記錄）。如果您有環境物件，則應用程式可作為
env.app使用。- 環境
建置環境物件（通常稱為
env）是BuildEnvironment的執行個體。它負責剖析來源文件、儲存有關文件集合的所有中繼資料，並在每次建置後序列化到磁碟。其 API 提供與存取中繼資料、解析參考等相關的方法。擴充套件也可以使用它來快取應在增量重建中持續存在的資訊。
如果您有應用程式或建置器物件，則環境可作為
app.env或builder.env使用。- 建置器
建置器物件（通常稱為
builder）是Builder特定子類別的執行個體。每個建置器類別都知道如何將剖析的文件轉換為輸出格式，或以其他方式處理它們（例如，檢查外部連結）。如果您有應用程式物件，則建置器可作為
app.builder使用。- 設定
設定物件（通常稱為
config）提供在conf.py中設定的設定值作為屬性。它是Config的執行個體。設定可作為
app.config或env.config使用。
若要查看如何使用這些物件的範例，請參閱教學課程。
建置階段¶
為了理解擴充機制，至關重要的一件事是 Sphinx 專案的建置方式：這在幾個階段中進行。
![digraph phases {
graph [
rankdir = LR
]
node [
shape = rect;
style = filled;
fillcolor ="#f7f7f7";
fontcolor = "#0a507a"
]
Initialization -> Reading;
Reading -> "Consistency checks";
"Consistency checks" -> Resolving;
Resolving -> Writing;
}](../_images/graphviz-339e3ad43e173f7c950f79bf4d41f82f906d2175.png)
建置階段¶
階段 0：初始化
在此階段，幾乎沒有我們感興趣的事情發生。來源目錄被搜尋來源檔案，並初始化擴充套件。如果存在儲存的建置環境，則載入它，否則建立一個新的環境。
階段 1：讀取
在階段 1 中，所有來源檔案（以及後續建置中，新的或已變更的檔案）都會被讀取和剖析。這是指令和角色被 docutils 遇到，並執行相應程式碼的階段。此階段的輸出是每個來源檔案的 *doctree*；這是一個 docutils 節點樹狀結構。對於在讀取所有現有檔案之前未完全瞭解的文件元素，會建立臨時節點。
docutils 提供了節點，這些節點記錄在 docutils 文件中。Sphinx 也提供了額外的節點，並在此處記錄。
在讀取期間，建置環境會使用已讀取文件的所有中繼資料和交叉參考資料進行更新，例如標籤、標題名稱、描述的 Python 物件和索引項目。這將在稍後用於替換臨時節點。
剖析的 doctree 儲存在磁碟上，因為不可能將所有 doctree 都保存在記憶體中。
階段 2：一致性檢查
執行一些檢查以確保建置的文件中沒有意外情況。
階段 3：解析
現在已知所有現有文件的中繼資料和交叉參考資料，所有臨時節點都將被可以轉換為輸出的節點替換，這些節點使用稱為轉換的元件。例如，為存在的物件參考建立連結，並為不存在的物件參考建立簡單的文字節點。
階段 4：寫入
此階段將解析的 doctree 轉換為所需的輸出格式，例如 HTML 或 LaTeX。這透過所謂的 docutils writer 進行，該 writer 訪問每個 doctree 的個別節點，並在此過程中產生一些輸出。
注意
某些建置器偏離此一般建置計畫，例如，檢查外部連結的建置器只需要剖析的 doctree，因此沒有階段 2-4。
如需應用範例，請參閱擴充建置過程。
擴充套件元資料¶
在版本 1.3 中新增。
setup() 函數應傳回字典。Sphinx 將其視為擴充套件的中繼資料。目前可辨識的中繼資料金鑰為
'version'識別擴充套件版本的字串。它用於擴充套件版本需求檢查（請參閱
needs_extensions）和資訊目的。如果未傳回版本字串，則預設使用'unknown version'。'env_version'一個非零正整數，用於記錄擴充套件儲存在環境中的資料版本。
注意
如果未設定
'env_version'，則擴充套件**不得**直接在環境物件 (env) 上儲存任何資料或狀態。如果擴充套件使用
env物件來儲存資料，則必須定義此金鑰。每當儲存資料的類型、結構或意義發生變更時，都必須遞增版本號碼，以確保 Sphinx 不會嘗試從快取的環境載入無效資料。在版本 1.8 中新增。
'parallel_read_safe'一個布林值，指定在載入擴充套件時是否可以使用平行讀取來源檔案。預設值為
False，這表示在檢查您的擴充套件是否安全以進行平行讀取後，您必須明確指定它。重要
當 *parallel-read-safe* 為
True時，擴充套件必須滿足以下條件擴充套件的核心邏輯在讀取階段期間可以平行執行。
如果擴充套件在讀取階段期間將資料儲存到建置環境物件 (
env)，則它具有env-merge-info和env-purge-doc事件的事件處理常式。
'parallel_write_safe'一個布林值，指定在載入擴充套件時是否可以使用平行寫入輸出檔案。由於擴充套件通常不會對該過程產生負面影響，因此預設值為
True。重要
當 *parallel-write-safe* 為
True時，擴充套件必須滿足以下條件擴充套件的核心邏輯在寫入階段期間可以平行執行。
用於撰寫擴充套件的 API¶
以下章節更完整地描述了您在開發 Sphinx 擴充套件時可用的工具。有些是 Sphinx 的核心（例如 應用程式 API），而另一些則觸發特定行為（例如 i18n API）