實用工具

Sphinx 提供了實用工具類別和函式來開發擴充功能。

組件的基礎類別

這些基礎類別對於讓您的擴充功能輕鬆取得 Sphinx 組件 (例如 Config, BuildEnvironment 等) 非常有用。

注意

它們的子類別可能無法與純 docutils 搭配使用，因為它們與 Sphinx 強烈耦合。

class sphinx.transforms.SphinxTransform(document, startnode=None)

Transforms 的基礎類別。

與 docutils.transforms.Transform 相比，此類別改善了 Sphinx API 的可存取性。

property app: Sphinx

參考 Sphinx 物件。

property config: Config

參考 Config 物件。

property env: BuildEnvironment

參考 BuildEnvironment 物件。

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)

後期轉換的基礎類別。

後期轉換會被調用來修改文件，以便為輸出重新建構文件。它們解析參考、轉換圖片、為每種輸出格式進行特殊轉換等等。此類別有助於實作這些後期轉換。

apply(**kwargs: Any) → None

覆寫以將轉換套用到文件樹。

is_supported() → bool

檢查此轉換是否適用於目前的建置器。

run(**kwargs: Any) → None

後期轉換的主要方法。

子類別應該覆寫此方法，而不是 apply()。

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

Sphinx 指令的基礎類別。

此類別為 Sphinx 指令提供輔助方法。

版本 1.8 新增。

注意

此類別的子類別可能無法與 docutils 搭配使用。此類別與 Sphinx 強烈耦合。

get_location() → str

取得用於記錄的目前位置資訊。

版本 4.2 新增。

get_source_info() → tuple[str, int]

取得來源和行號。

版本 3.0 新增。

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node]

將指令的內容解析為節點。

參數：

allow_section_headings – 指令的內容是否允許標題 (章節)？ 請注意，此選項會繞過 Docutils 對於文件樹結構的常規檢查，濫用此選項可能會導致不連貫的文件樹。在 Docutils 中，章節節點應僅為 Structural 節點的子節點，其中包括 document、section 和 sidebar 節點。

版本 7.4 新增。

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]]

將 *text* 解析為行內元素。

參數：

• text – 要解析的文字，應為單行或段落。這不能包含任何結構元素 (標題、轉場、指令等)。

• lineno – 解譯文字開始的行號。

傳回：

節點列表 (文字和行內元素) 和 system_messages 列表。

版本 7.4 新增。

parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node]

將 *text* 解析為節點。

參數：

• text – 文字，以字串形式。也接受 StringList。

• allow_section_headings – *text* 中是否允許標題 (章節)？ 請注意，此選項會繞過 Docutils 對於文件樹結構的常規檢查，濫用此選項可能會導致不連貫的文件樹。在 Docutils 中，章節節點應僅為 Structural 節點的子節點，其中包括 document、section 和 sidebar 節點。

• offset – 內容的偏移量。

版本 7.4 新增。

set_source_info(node: Node) → None

將來源和行號設定到節點。

版本 2.1 新增。

property config: Config

參考 Config 物件。

版本 1.8 新增。

property env: BuildEnvironment

參考 BuildEnvironment 物件。

版本 1.8 新增。

class sphinx.util.docutils.SphinxRole

Sphinx 角色的基礎類別。

此類別為 Sphinx 角色提供輔助方法。

版本 2.0 新增。

注意

此類別的子類別可能無法與 docutils 搭配使用。此類別與 Sphinx 強烈耦合。

get_location() → str

取得用於記錄的目前位置資訊。

版本 4.2 新增。

property config: Config

參考 Config 物件。

版本 2.0 新增。

content: Sequence[str]

字串列表，用於自訂的指令內容 (來自 “role” 指令)。

property env: BuildEnvironment

參考 BuildEnvironment 物件。

版本 2.0 新增。

inliner: Inliner

docutils.parsers.rst.states.Inliner 物件。

lineno: int

解譯文字開始的行號。

name: str

文件中實際使用的角色名稱。

options: dict[str, Any]

指令選項字典，用於自訂 (來自 “role” 指令)。

rawtext: str

包含整個解譯文字輸入的字串。

text: str

解譯的文字內容。

class sphinx.util.docutils.ReferenceRole

參考角色的基礎類別。

參考角色可以接受 link title <target> 樣式作為角色的文字。解析結果；連結標題和目標將儲存到 self.title 和 self.target。

版本 2.0 新增。

disabled: bool

布林值表示參考是否停用。

has_explicit_title: bool

布林值表示角色是否具有明確標題。

target: str

解譯文字的連結目標。

title: str

解譯文字的連結標題。

class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)

圖片轉換器的基礎類別。

圖片轉換器是一種 Docutils 轉換模組。它用於將建置器不支援的圖片檔案轉換為該建置器適當的格式。

例如，LaTeX builder 支援 PDF、PNG 和 JPEG 作為圖片格式。但是它不支援 SVG 圖片。在這種情況下，使用圖片轉換器可以將這些不支援的圖片嵌入到文件中。其中一個圖片轉換器；sphinx.ext.imgconverter 可以使用 Imagemagick 在內部將 SVG 圖片轉換為 PNG 格式。

製作自訂圖片轉換器有三個步驟

1. 建立 ImageConverter 類別的子類別

2. 覆寫 conversion_rules、is_available() 和 convert()

3. 使用 Sphinx.add_post_transform() 將您的圖片轉換器註冊到 Sphinx

convert(_from: str | PathLike[str], _to: str | PathLike[str]) → bool

將圖片檔案轉換為預期的格式。

_from 是來源圖片檔案的路徑，而 _to 是目標檔案的路徑。

is_available() → bool

傳回圖片轉換器是否可用。

available: bool | None = None

轉換器是否可用。將在首次建置呼叫時填入。結果在同一個程序中共享。

conversion_rules: list[tuple[str, str]] = []

圖片轉換器支援的轉換規則。它表示為來源圖片格式 (MIME 類型) 和目標格式的配對列表

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]

default_priority = 200

此轉換的數值優先級，0 到 999 (覆蓋)。

實用工具組件

class sphinx.events.EventManager(app: Sphinx)

Sphinx 的事件管理器。

add(name: str) → None

註冊自訂的 Sphinx 事件。

connect(name: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int) → int

connect(name: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int) → int

connect(name: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int) → int

connect(name: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int) → int

connect(name: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int) → int

connect(name: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int) → int

connect(name: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int) → int

connect(name: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int) → int

connect(name: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], BuildEnvironment], None], priority: int) → int

connect(name: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int) → int

connect(name: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int) → int

connect(name: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int) → int

connect(name: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int) → int

connect(name: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int) → int

connect(name: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int) → int

connect(name: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int) → int

connect(name: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int) → int

connect(name: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int) → int

connect(name: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict[str, Any], nodes.document], str | None], priority: int) → int

connect(name: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int) → int

connect(name: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int) → int

connect(name: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int) → int

connect(name: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], priority: int) → int

connect(name: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int) → int

connect(name: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int) → int

connect(name: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], priority: int) → int

connect(name: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int) → int

connect(name: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int) → int

connect(name: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int) → int

connect(name: str, callback: Callable[..., Any], priority: int) → int

連接處理器到特定事件。

disconnect(listener_id: int) → None

斷開處理器連接。

emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[Any]

發送 Sphinx 事件。

emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any

發送 Sphinx 事件並返回第一個結果。

此函式會返回第一個未返回 None 的處理器的結果。

實用工具函式

sphinx.util.parsing.nested_parse_to_nodes(state: RSTState, text: str | StringList, *, source: str = '<generated text>', offset: int = 0, allow_section_headings: bool = True, keep_title_context: bool = False) → list[Node]

將 *text* 解析為節點。

參數：

• state – 狀態機狀態。必須為 RSTState 的子類別。

• text – 文字，以字串形式。也接受 StringList。

• source – 文字的來源，用於建立新的 StringList 時。

• offset – 內容的偏移量。

• allow_section_headings – *text* 中是否允許標題 (章節)？ 請注意，此選項會繞過 Docutils 對於文件樹結構的常規檢查，濫用此選項可能會導致不連貫的文件樹。在 Docutils 中，章節節點應僅為 Structural 節點的子節點，其中包括 document、section 和 sidebar 節點。

• keep_title_context – 如果此值為 False (預設值)，則會將 *content* 解析為如同它是獨立文件一樣，這表示標題裝飾 (例如底線) 不需要與周圍的文件相符。當解析的內容來自完全不同的上下文 (例如 docstring) 時，這非常有用。如果此值為 True，則標題底線必須與周圍文件中的底線相符，否則行為未定義。

版本 7.4 新增。

實用工具類型

class sphinx.util.typing.ExtensionMetadata

擴充套件的 setup() 函式傳回的 metadata。

請參閱 擴充套件 metadata。

env_version: int

一個整數，用於識別擴充功能所新增的環境資料版本。

parallel_read_safe: bool

指出擴充功能是否支援平行讀取原始檔。

parallel_write_safe: bool

指出擴充功能是否支援平行寫入輸出檔 (預設值：True)。

version: str

擴充功能版本 (預設值：'unknown version')。

上一頁

i18n API

下一頁

測試 API