Builder API

class sphinx.builders.Builder

這是所有 builder 的基礎類別。

它遵循這個基本工作流程

標準 Sphinx 建置工作流程的呼叫圖

可覆寫的屬性

這些類別屬性應該在 builder 子類別中設定

name: str = ''

builder 的名稱。這是用來在命令列上選擇 builder 的值。

format: str = ''

builder 的輸出格式，如果沒有產生文件輸出，則為 ''。這通常是檔案副檔名，例如 "html"，雖然接受任何字串值。builder 的格式字串可以被各種組件使用，例如 SphinxPostTransform 或擴充功能，以判斷它們與 builder 的相容性。

epilog: str = ''

成功完成建置時發出的訊息。這可以是 printf 樣式的範本字串，帶有以下鍵：outdir, project

allow_parallel: bool = False

是否可以安全地進行平行 write_doc() 呼叫。

supported_image_types: list[str] = []

builder 支援的影像格式的 MIME 類型列表。影像檔案會按照它們在此處出現的順序搜尋。

supported_remote_images: bool = False

builder 可以產生輸出文件，這些文件在開啟時可能會提取外部影像。

supported_data_uri_images: bool = False

builder 產生的檔案格式允許使用 data-URI 嵌入影像。

default_translator_class: type[nodes.NodeVisitor]

builder 的預設 translator 類別。這可以被 set_translator() 覆寫。

核心方法

這些方法定義了核心建置工作流程，不得覆寫

final build_all() → None

建置所有來源檔案。

final build_specific(filenames: Sequence[Path]) → None

僅針對 filenames 中的變更重建所需的部分。

final build_update() → None

僅重建自上次建置以來已變更或新增的內容。

final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') → None

主要建置方法，通常由特定的 build_* 方法呼叫。

首先更新環境，然後呼叫 write()。

final read() → list[str]

(重新)讀取自上次更新以來新增或變更的所有檔案。

將所有環境 docname 儲存為標準格式 (即使用 SEP 作為分隔符號，而不是 os.path.sep)。

final read_doc(docname: str, *, _cache: bool = True) → None

剖析檔案並為 doctree 新增/更新庫存項目。

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None

將 doctree 寫入檔案，以作為重新建置的快取。

final write(build_docnames: Iterable[str] | None, updated_docnames: Iterable[str], method: Literal['all', 'specific', 'update'] = 'update') → None

寫入 builder 特定的輸出檔案。

抽象方法

這些必須在 builder 子類別中實作

get_outdated_docs() → str | Iterable[str]

傳回過期的輸出檔案的可迭代物件，或描述更新建置將建置內容的字串。

如果 builder 沒有輸出對應於來源檔案的個別檔案，則在此處傳回字串。如果有的話，傳回需要寫入的那些檔案的可迭代物件。

write_doc(docname: str, doctree: document) → None

寫入文件的輸出檔案

參數:

• docname – 文件名稱。

• doctree – 定義要寫入的內容。

輸出檔案名稱必須在這個方法中決定，通常透過呼叫 get_target_uri() 或 get_relative_uri()。

get_target_uri(docname: str, typ: str | None = None) → str

傳回文件名稱的目標 URI。

typ 可以用來限定個別 builder 的連結特性。

可覆寫的方法

這些方法可以在 builder 子類別中覆寫

init() → None

載入必要的範本並執行初始化。預設實作不做任何事。

write_documents(docnames: Set[str]) → None

寫入 docnames 中的所有文件。

如果 builder 沒有為每個文件建立輸出檔案，則可以覆寫這個方法。

prepare_writing(docnames: Set[str]) → None

您可以在執行 write_doc() 之前新增邏輯的地方

copy_assets() → None

在寫入之前複製 assets (影像、靜態檔案等) 的地方

get_relative_uri(from_: str, to: str, typ: str | None = None) → str

傳回兩個來源檔案名稱之間的相對 URI。

引發:

NoUri 如果沒有辦法傳回合理的 URI。

finish() → None

完成建置程序。

預設實作不做任何事。

屬性

可以從 builder 實例呼叫的屬性

events

一個 EventManager 物件。

可覆寫的屬性 (擴充功能)

Builder 子類別可以設定這些屬性以支援內建擴充功能

supported_linkcode: str

預設情況下，linkcode 擴充功能只會為 html builder 注入參考。supported_linkcode 類別屬性可以在非 HTML builder 中定義，以支援管理由 linkcode 產生的參考。這個屬性的預期值是與 only 相容的運算式。

例如，如果建構器被命名為 custom-builder，則可以使用以下內容

class CustomBuilder(Builder):
    supported_linkcode = 'custom-builder'
    ...

上一頁

建置環境 API

下一頁

環境收集器 API