應用程式 API

每個 Sphinx 擴充套件都是一個 Python 模組，至少有一個 setup() 函數。此函數在初始化時被呼叫，並帶有一個引數，即代表 Sphinx 程序的應用程式物件。

class sphinx.application.Sphinx

此應用程式物件具有以下描述的公開 API。

擴充套件設定

這些方法通常在擴充套件的 setup() 函數中呼叫。

使用 Sphinx 擴充套件 API 的範例可以在 sphinx.ext 套件中看到。

Sphinx.setup_extension(extname: str) → None

匯入並設定 Sphinx 擴充套件模組。

載入由模組名稱給定的擴充套件。如果您的擴充套件需要另一個擴充套件提供的功能，請使用此方法。如果呼叫兩次，則為空操作。

static Sphinx.require_sphinx(version: tuple[int, int] | str) → None

如果需要，檢查 Sphinx 版本。

將版本與正在運行的 Sphinx 版本進行比較，並在版本太舊時中止建置。

參數:

version – 所需版本，格式為 major.minor 或 (major, minor)。

在 1.0 版本中新增。

在 7.1 版本中變更：version 的類型現在允許 (major, minor) 格式。

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

Sphinx.connect(event: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int = 500) → int

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Sphinx.connect(event: Literal['autodoc-process-docstring'], callback: _AutodocProcessDocstringListener, priority: int = 500) → int

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

Sphinx.connect(event: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | Sphinx.connect(event: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int = 500) → int

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

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

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

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

Sphinx.connect(event: str, callback: Callable[..., Any], priority: int = 500) → int

註冊 callback 以在發出 event 時調用。

如需可用核心事件和回調函數引數的詳細資訊，請參閱事件回調 API。

參數:

• event – 目標事件的名稱

• callback – 事件的回調函數

• priority – 回調的優先順序。回調將按照priority（遞增）的順序調用。

返回:

一個監聽器 ID。它可以用於 disconnect()。

變更版本 3.0: 支援 priority

Sphinx.disconnect(listener_id: int) → None

取消註冊 listener_id 的回調。

參數:

listener_id – connect() 返回的 listener_id

Sphinx.add_builder(builder: type[Builder], override: bool = False) → None

註冊一個新的 builder。

參數:

• builder – 一個 builder 類別

• override – 如果為 true，即使另一個 builder 已安裝為相同的名稱，仍強制安裝 builder

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_config_value(name: str, default: Any, rebuild: _ConfigRebuild, types: type | Collection[type] | ENUM = (), description: str = '') → None

註冊一個配置值。

這對於 Sphinx 識別新值並相應地設定預設值是必要的。

參數:

• name – 配置值的名稱。建議以擴充功能名稱作為前綴（例如 html_logo、 epub_title）

• default – 配置的預設值。

• rebuild –

  重建的條件。它必須是以下值之一

  • 'env' 如果設定中的變更僅在文件被解析時生效 – 這表示必須重建整個環境。

  • 'html' 如果設定中的變更需要完整重建 HTML 文件。

  • '' 如果設定中的變更不需要任何特殊的重建。

• types – 配置值的類型。可以指定類型列表。例如，[str] 用於描述採用字串值的配置。

• description – 配置值的簡短描述。

變更版本 0.4: 如果 default 值是可調用的，則將使用配置物件作為引數調用它，以便取得預設值。這可以用於實作預設值取決於其他值的配置值。

變更版本 0.6: 將 rebuild 從簡單的布林值（相當於 '' 或 'env'）變更為字串。但是，仍然接受布林值並在內部轉換。

新增版本 7.4: description 參數。

Sphinx.add_event(name: str) → None

註冊一個名為 name 的事件。

這是發出事件所必需的。

參數:

name – 事件的名稱

Sphinx.set_translator(name: str, translator_class: type[nodes.NodeVisitor], override: bool = False) → None

註冊或覆寫 Docutils 翻譯器類別。

這用於註冊自訂輸出翻譯器或替換內建翻譯器。這允許擴充功能使用自訂翻譯器，並為翻譯器定義自訂節點（請參閱 add_node()）。

參數:

• name – 翻譯器的 builder 名稱

• translator_class – 一個翻譯器類別

• override – 如果為 true，即使另一個翻譯器已安裝為相同的名稱，仍強制安裝翻譯器

新增版本 1.3。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_node(node: type[Element], override: bool = False, **kwargs: _NodeHandlerPair) → None

註冊一個 Docutils 節點類別。

這對於 Docutils 內部結構是必要的。將來也可用於驗證已解析文件中的節點。

參數:

• node – 一個節點類別

• kwargs – 每個 builder 的 Visitor 函數（請參閱下文）

• override – 如果為 true，即使另一個節點已安裝為相同的名稱，仍強制安裝節點

可以將 Sphinx HTML、LaTeX、text 和 manpage writers 的節點 visitor 函數作為關鍵字引數給出：關鍵字應為 'html'、 'latex'、 'text'、 'man'、 'texinfo' 或任何其他支援的翻譯器中的一個或多個，值為 (visit, depart) 方法的 2 元組。depart 可以是 None，如果 visit 函數引發 docutils.nodes.SkipNode。範例

class math(docutils.nodes.Element): ...

def visit_math_html(self, node):
    self.body.append(self.starttag(node, 'math'))

def depart_math_html(self, node):
    self.body.append('</math>')

app.add_node(math, html=(visit_math_html, depart_math_html))

顯然，對於您未指定 visitor 方法的翻譯器，當在要翻譯的文件中遇到節點時，將會崩潰。

變更版本 0.5: 新增了對提供 visitor 函數的關鍵字引數的支援。

Sphinx.add_enumerable_node(node: type[Element], figtype: str, title_getter: TitleGetter | None = None, override: bool = False, **kwargs: tuple[_NodeHandler, _NodeHandler]) → None

將 Docutils 節點類別註冊為 numfig 目標。

Sphinx 會自動編號節點。然後使用者可以使用 numref 參考它。

參數:

• node – 一個節點類別

• figtype – 可列舉節點的類型。每個 figtype 都有個別的編號序列。作為系統 figtype，定義了 figure、 table 和 code-block。可以將自訂節點新增至這些預設 figtype。如果給定新的 figtype，也可以定義新的自訂 figtype。

• title_getter – 一個 getter 函數，用於取得節點的標題。它接受可列舉節點的實例，並且必須將其標題作為字串傳回。標題用於 ref 參考的預設標題。預設情況下，Sphinx 從節點中搜尋 docutils.nodes.caption 或 docutils.nodes.title 作為標題。

• kwargs – 每個 builder 的 Visitor 函數（與 add_node() 相同）

• override – 如果為 true，即使另一個節點已安裝為相同的名稱，仍強制安裝節點

新增版本 1.4。

Sphinx.add_directive(name: str, cls: type[Directive], override: bool = False) → None

註冊一個 Docutils 指令。

參數:

• name – 指令的名稱

• cls – 一個指令類別

• override – 如果為 false，如果另一個指令已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝指令。

例如，一個名為 my-directive 的自訂指令將像這樣新增

from docutils.parsers.rst import Directive, directives

class MyDirective(Directive):
    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = True
    option_spec = {
        'class': directives.class_option,
        'name': directives.unchanged,
    }

    def run(self):
        pass

def setup(app):
    app.add_directive('my-directive', MyDirective)

如需更多詳細資訊，請參閱 Docutils 文件。

變更版本 0.6: 現在支援 Docutils 0.5 樣式的指令類別。

自版本 1.8 起棄用: Docutils 0.4 樣式（基於函數）的指令支援已棄用。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_role(name: str, role: Any, override: bool = False) → None

註冊一個 Docutils 角色。

參數:

• name – 角色的名稱

• role – 一個角色函數

• override – 如果為 false，如果另一個角色已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝角色。

有關角色函數的更多詳細資訊，請參閱 Docutils 文件。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_generic_role(name: str, nodeclass: type[Node], override: bool = False) → None

註冊一個通用的 Docutils 角色。

註冊一個 Docutils 角色，除了將其內容包裝在 nodeclass 給定的節點中之外，什麼也不做。

參數:

override – 如果為 false，如果另一個角色已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝角色。

新增版本 0.6。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_domain(domain: type[Domain], override: bool = False) → None

註冊一個 domain。

參數:

• domain – 一個 domain 類別

• override – 如果為 false，如果另一個 domain 已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝 domain。

在 1.0 版本中新增。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_directive_to_domain(domain: str, name: str, cls: type[Directive], override: bool = False) → None

在 domain 中註冊一個 Docutils 指令。

與 add_directive() 類似，但指令會新增到名為 domain 的 domain 中。

參數:

• domain – 目標 domain 的名稱

• name – 指令的名稱

• cls – 一個指令類別

• override – 如果為 false，如果另一個指令已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝指令。

在 1.0 版本中新增。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_role_to_domain(domain: str, name: str, role: RoleFunction | XRefRole, override: bool = False) → None

在 domain 中註冊一個 Docutils 角色。

與 add_role() 類似，但角色會新增到名為 domain 的 domain 中。

參數:

• domain – 目標 domain 的名稱

• name – 角色的名稱

• role – 角色函數

• override – 如果為 false，如果另一個角色已安裝為相同的名稱，則不安裝它。如果為 true，則無條件安裝角色。

在 1.0 版本中新增。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_index_to_domain(domain: str, index: type[Index], _override: bool = False) → None

為網域註冊自訂索引。

將自訂索引類別新增至名為domain的網域。

參數:

• domain – 目標 domain 的名稱

• index – 索引類別

• override – 若為 false，如果已安裝另一個同名的索引，則不要安裝。若為 true，則無條件安裝索引。

在 1.0 版本中新增。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_object_type(directivename: str, rolename: str, indextemplate: str = '', parse_node: Callable[[BuildEnvironment, str, addnodes.desc_signature], str] | None = None, ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', doc_field_types: Sequence[Field] = (), override: bool = False) → None

註冊新的物件類型。

此方法是一種非常方便的方式來新增可以交叉引用的新物件類型。它會執行以下操作：

• 建立一個新的指令 (稱為 directivename) 以記錄物件。如果 indextemplate 為非空，它將自動新增索引條目；如果給定，它必須正好包含一個 %s 的實例。請參閱下面的範例，了解如何解釋範本。

• 建立一個新的角色 (稱為 rolename) 以交叉引用到這些物件描述。

• 如果您提供 parse_node，它必須是一個函數，該函數接受一個字串和一個 docutils 節點，並且必須使用從字串解析的子節點來填充該節點。然後，它必須傳回要在交叉引用和索引條目中使用的項目名稱。有關範例，請參閱此文件來源中的 conf.py 檔案。

• objname (如果未給定，則預設為 directivename) 命名物件的類型。它用於列出物件，例如在搜尋結果中。

例如，如果您在自訂 Sphinx 擴充功能中有此呼叫

app.add_object_type('directive', 'dir', 'pair: %s; directive')

您可以在文件中使用此標記

.. rst:directive:: function

   Document a function.

<...>

See also the :rst:dir:`function` directive.

對於指令，將產生索引條目，就好像您已在前面加上

.. index:: pair: function; directive

除非您提供 ref_nodeclass 參數，否則參考節點將為 literal 類別（因此它將以比例字體呈現，如適合程式碼）。ref_nodeclass 參數必須是 docutils 節點類別。最有用的類別是 docutils.nodes.emphasis 或 docutils.nodes.strong – 如果您不想要進一步的文字裝飾，也可以使用 docutils.nodes.generated。如果文字應被視為文字 (例如，不進行智慧引號替換)，但不具有打字機樣式，請使用 sphinx.addnodes.literal_emphasis 或 sphinx.addnodes.literal_strong。

對於角色內容，您具有與標準 Sphinx 角色相同的語法可能性（請參閱 語法）。

如果 override 為 True，即使已安裝具有相同名稱的 object_type，也會強制安裝給定的 object_type。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_crossref_type(directivename: str, rolename: str, indextemplate: str = '', ref_nodeclass: type[nodes.TextElement] | None = None, objname: str = '', override: bool = False) → None

註冊新的交叉引用物件類型。

此方法與 add_object_type() 非常相似，不同之處在於它產生的指令必須為空，並且不會產生任何輸出。

這表示您可以將語義目標新增至來源，並使用自訂角色而不是通用角色 (例如 ref) 來引用它們。範例呼叫

app.add_crossref_type(
    'topic', 'topic', 'single: %s', docutils.nodes.emphasis
)

範例用法

.. topic:: application API

The application API
-------------------

Some random text here.

See also :topic:`this section <application API>`.

（當然，topic 指令之後的元素不必是章節。）

參數:

override – 若為 false，如果已安裝另一個同名的交叉引用類型，則不要安裝。若為 true，則無條件安裝交叉引用類型。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_transform(transform: type[Transform]) → None

註冊一個在解析後套用的 Docutils 轉換。

將標準 docutils Transform 子類別 transform 新增至在 Sphinx 解析 reST 文件後套用的轉換清單。

參數:

transform – 轉換類別

Sphinx 轉換的優先順序範圍類別

優先順序	Sphinx 中的主要用途
0-99	修復 docutils 的無效節點。轉換 doctree。
100-299	準備
300-399	早期
400-699	主要
700-799	後處理。修改文字和參考的期限。
800-899	收集參考和被參考的節點。網域處理。
900-999	最終確定和清理。

參考：轉換優先順序範圍類別

Sphinx.add_post_transform(transform: type[Transform]) → None

註冊一個在寫入前套用的 Docutils 轉換。

將標準 docutils Transform 子類別 transform 新增至在 Sphinx 寫入文件之前套用的轉換清單。

參數:

transform – 轉換類別

Sphinx.add_js_file(filename: str | None, priority: int = 500, loading_method: str | None = None, **kwargs: Any) → None

註冊要包含在 HTML 輸出中的 JavaScript 檔案。

參數:

• filename – 預設 HTML 範本將包含的 JavaScript 檔案名稱。它必須是相對於 HTML 靜態路徑的路徑，或是具有協定的完整 URI，或是 None。None 值用於建立內嵌 <script> 標籤。請參閱下方 kwargs 的描述。

• priority – 檔案會依優先順序升序包含。如果多個 JavaScript 檔案具有相同的優先順序，則這些檔案將依註冊順序包含。請參閱下方「JavaScript 檔案的優先順序範圍」清單。

• loading_method – JavaScript 檔案的載入方法。允許使用 'async' 或 'defer'。

• kwargs – 額外的關鍵字引數會作為 <script> 標籤的屬性包含。如果給定了特殊關鍵字引數 body，則其值將作為 <script> 標籤的內容新增。

範例

app.add_js_file('example.js')
# => <script src="_static/example.js"></script>

app.add_js_file('example.js', loading_method='async')
# => <script src="_static/example.js" async="async"></script>

app.add_js_file(None, body="var myVariable = 'foo';")
# => <script>var myVariable = 'foo';</script>

JavaScript 檔案的優先順序範圍

優先順序	Sphinx 中的主要用途
200	內建 JavaScript 檔案的預設優先順序
500	擴充功能的預設優先順序
800	html_js_files 的預設優先順序

當擴充功能在 html-page-context 事件上呼叫此方法時，可以將 JavaScript 檔案新增至特定的 HTML 頁面。

在版本 0.5 中新增。

版本 1.8 中變更：從 app.add_javascript() 重新命名。並且允許關鍵字引數作為 script 標籤的屬性。

版本 3.5 中變更：採用 priority 引數。允許將 JavaScript 檔案新增至特定頁面。

版本 4.4 中變更：採用 loading_method 引數。允許變更 JavaScript 檔案的載入方法。

Sphinx.add_css_file(filename: str, priority: int = 500, **kwargs: Any) → None

註冊要包含在 HTML 輸出中的樣式表。

參數:

• filename – 預設 HTML 範本將包含的 CSS 檔案名稱。它必須是相對於 HTML 靜態路徑的路徑，或是具有協定的完整 URI。

• priority – 檔案會依優先順序升序包含。如果多個 CSS 檔案具有相同的優先順序，則這些檔案將依註冊順序包含。請參閱下方「CSS 檔案的優先順序範圍」清單。

• kwargs – 額外的關鍵字引數會作為 <link> 標籤的屬性包含。

範例

app.add_css_file('custom.css')
# => <link rel="stylesheet" href="_static/custom.css" type="text/css" />

app.add_css_file('print.css', media='print')
# => <link rel="stylesheet" href="_static/print.css"
#          type="text/css" media="print" />

app.add_css_file('fancy.css', rel='alternate stylesheet', title='fancy')
# => <link rel="alternate stylesheet" href="_static/fancy.css"
#          type="text/css" title="fancy" />

CSS 檔案的優先順序範圍

優先順序	Sphinx 中的主要用途
200	內建 CSS 檔案的預設優先順序
500	擴充功能的預設優先順序
800	html_css_files 的預設優先順序

當擴充功能在 html-page-context 事件上呼叫此方法時，可以將 CSS 檔案新增至特定的 HTML 頁面。

在 1.0 版本中新增。

版本 1.6 中變更：可使用引數 alternate (布林值) 和 title (字串) 提供選用的 alternate 和/或 title 屬性。預設值為無標題，且 alternate = False。如需更多資訊，請參閱 文件。

版本 1.8 中變更：從 app.add_stylesheet() 重新命名。並且允許關鍵字引數作為 link 標籤的屬性。

版本 3.5 中變更：採用 priority 引數。允許將 CSS 檔案新增至特定頁面。

Sphinx.add_latex_package(packagename: str, options: str | None = None, after_hyperref: bool = False) → None

註冊要包含在 LaTeX 原始碼中的套件。

將 packagename 新增至 LaTeX 原始碼將包含的套件清單。如果您提供 options，它將被視為 usepackage 宣告。如果您將 after_hyperref 設定為真值，則套件將在載入 hyperref 套件後載入。

app.add_latex_package('mypackage')
# => \usepackage{mypackage}
app.add_latex_package('mypackage', 'foo,bar')
# => \usepackage[foo,bar]{mypackage}

新增版本 1.3。

版本 3.1 中新增：after_hyperref 選項。

Sphinx.add_lexer(alias: str, lexer: type[Lexer]) → None

註冊用於原始碼的新詞法分析器。

使用 lexer 來醒目提示具有給定語言別名的程式碼區塊。

新增版本 0.6。

版本 2.1 中變更：採用詞法分析器類別作為引數。

版本 4.0 中變更：移除對詞法分析器實例作為引數的支援。

Sphinx.add_autodocumenter(cls: type[Documenter], override: bool = False) → None

為 autodoc 擴充功能註冊新的文件編寫器類別。

將 cls 新增為 sphinx.ext.autodoc 擴充功能的新文件編寫器類別。它必須是 sphinx.ext.autodoc.Documenter 的子類別。這允許自動記錄新類型的物件。請參閱 autodoc 模組的原始碼，以取得有關如何子類別化 Documenter 的範例。

如果 override 為 True，即使已安裝具有相同名稱的文件編寫器，也會強制安裝給定的 cls。

請參閱 開發 autodoc 擴充功能。

新增版本 0.6。

版本 2.2 中變更：新增 override 關鍵字。

Sphinx.add_autodoc_attrgetter(typ: type, getter: Callable[[Any, str, Any], Any]) → None

為 autodoc 擴充功能註冊新的類似 getattr 的函數。

新增 getter，它必須是一個與 getattr() 內建函數介面相容的函數，作為 typ 實例物件的 autodoc 屬性 getter。然後，autodoc 需要取得類型屬性的所有情況都將由此函數而不是 getattr() 處理。

新增版本 0.6。

Sphinx.add_search_language(cls: type[SearchLanguage]) → None

為 HTML 搜尋索引註冊新的語言。

新增 cls，其必須為 sphinx.search.SearchLanguage 的子類別，作為建置 HTML 全文檢索索引的支援語言。該類別必須具有 lang 屬性，以指出其應使用的語言。請參閱 html_search_language。

在版本 1.1 中新增。

Sphinx.add_source_suffix(suffix: str, filetype: str, override: bool = False) → None

註冊來源檔案的後綴。

與 source_suffix 相同。使用者可以使用組態設定覆寫此設定。

參數:

override – 若為 false，則在已安裝相同後綴時，請勿安裝。若為 true，則無條件安裝後綴。

在版本 1.8 中新增。

Sphinx.add_source_parser(parser: type[Parser], override: bool = False) → None

註冊一個剖析器類別。

參數:

override – 若為 false，則在已為相同後綴安裝另一個剖析器時，請勿安裝。若為 true，則無條件安裝剖析器。

新增版本 1.4。

在版本 1.8 中變更：suffix 引數已被棄用。它僅接受 parser 引數。請改用 add_source_suffix() API 來註冊後綴。

變更版本 1.8: 新增 override 關鍵字。

Sphinx.add_env_collector(collector: type[EnvironmentCollector]) → None

註冊一個環境收集器類別。

請參閱 環境收集器 API。

在版本 1.6 中新增。

Sphinx.add_html_theme(name: str, theme_path: str | os.PathLike[str]) → None

註冊一個 HTML 主題。

name 是主題的名稱，而 theme_path 是主題的完整路徑（參考：以 Python 套件形式發佈您的主題）。

在版本 1.6 中新增。

Sphinx.add_html_math_renderer(name: str, inline_renderers: _MathsInlineRenderers | None = None, block_renderers: _MathsBlockRenderers | None = None) → None

註冊一個 HTML 的數學算式渲染器。

name 是數學算式渲染器的名稱。inline_renderers 和 block_renderers 都用作 HTML writer 的 visitor 函數：前者用於行內數學算式節點 (nodes.math)，後者用於區塊數學算式節點 (nodes.math_block)。關於 visitor 函數，請參閱 add_node() 以取得詳細資訊。

在版本 1.8 中新增。

Sphinx.add_message_catalog(catalog: str, locale_dir: str | os.PathLike[str]) → None

註冊一個訊息目錄。

參數:

• catalog – 目錄的名稱

• locale_dir – 訊息目錄的基礎路徑

如需更多詳細資訊，請參閱 sphinx.locale.get_translation()。

在版本 1.8 中新增。

Sphinx.is_parallel_allowed(typ: str) → bool

檢查是否允許平行處理。

參數:

typ – 處理類型；'read' 或 'write'。

Sphinx.set_html_assets_policy(policy: Literal['always', 'per_page']) → None

設定在 HTML 頁面中包含資源的策略。

• always：在所有頁面中包含資源

• per_page：僅在使用資源的頁面中包含資源

exception sphinx.application.ExtensionError

如果擴充功能 API 出現問題，所有這些方法都會引發此例外。

發射事件

class sphinx.application.Sphinx

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

發射 event 並將 arguments 傳遞至回呼函數。

傳回所有回呼的傳回值作為列表。請勿在擴充功能中發射核心 Sphinx 事件！

參數:

• event – 將發射的事件名稱

• args – 事件的引數

• allowed_exceptions – 回呼中允許的例外列表

在版本 3.1 中變更：新增 allowed_exceptions 以指定路徑穿透例外

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

發射 event 並將 arguments 傳遞至回呼函數。

傳回第一個未傳回 None 的回呼結果。

參數:

• event – 將發射的事件名稱

• args – 事件的引數

• allowed_exceptions – 回呼中允許的例外列表

在版本 0.5 中新增。

在版本 3.1 中變更：新增 allowed_exceptions 以指定路徑穿透例外

Sphinx 執行階段資訊

應用程式物件也以屬性形式提供執行階段資訊。

Sphinx.project

目標專案。請參閱 Project。

Sphinx.srcdir

來源目錄。

Sphinx.confdir

包含 conf.py 的目錄。

Sphinx.doctreedir

用於儲存 pickled doctrees 的目錄。

Sphinx.outdir

用於儲存建置文件的目錄。

Sphinx.fresh_env_used

True/False，表示此建置是否已建立新環境；若環境尚未初始化，則為 None。

Sphinx 核心事件

注意

已移至 事件回呼 API。

檢查 Sphinx 版本

使用此功能可使您的擴充功能適應 Sphinx 中的 API 變更。

sphinx.version_info = (8, 2, 0, 'final', 0)

版本資訊，以便更好地進行程式化使用。

一個包含五個元素的元組；對於 Sphinx 版本 1.2.1 beta 3，這將是 (1, 2, 1, 'beta', 3)。第四個元素可以是以下之一：alpha、beta、rc、final。final 的最後一個元素始終為 0。

在版本 1.2 中新增：在版本 1.2 之前，請檢查字串 sphinx.__version__。

Config 物件

class sphinx.config.Config(config: dict[str, Any] | None = None, overrides: dict[str, Any] | None = None)

組態檔抽象化。

Config 物件使所有組態選項的值都可作為屬性使用。

它透過 Sphinx.config 和 sphinx.environment.BuildEnvironment.config 屬性公開。例如，若要取得 language 的值，請使用 app.config.language 或 env.config.language。

樣板橋接器

class sphinx.application.TemplateBridge

此類別定義了「樣板橋接器」的介面，也就是一個類別，它根據樣板名稱和上下文來渲染樣板。

init(builder: Builder, theme: Theme | None = None, dirs: list[str] | None = None) → None

由 builder 呼叫以初始化樣板系統。

builder 是 builder 物件；您可能需要查看 builder.config.templates_path 的值。

theme 是 sphinx.theming.Theme 物件或 None；在後一種情況下，dirs 可以是要尋找樣板的固定目錄列表。

newest_template_mtime() → float

由 builder 呼叫，以判斷輸出檔案是否因樣板變更而過時。傳回已變更的最新樣板檔案的 mtime。預設實作傳回 0。

render(template: str, context: dict[str, Any]) → None

由 builder 呼叫，以使用指定的上下文（Python 字典）渲染作為檔案名稱提供的樣板。

render_string(template: str, context: dict[str, Any]) → str

由 builder 呼叫，以使用指定的上下文（Python 字典）渲染作為字串提供的樣板。

例外

exception sphinx.errors.SphinxError

Sphinx 錯誤的基底類別。

這是「友善」例外的基底類別。當引發此類例外時，Sphinx 將中止建置，並向使用者顯示例外類別和訊息。

鼓勵擴充功能從此例外衍生出其自訂錯誤。

未 從 SphinxError 衍生的例外會被視為非預期的，並向使用者顯示部分追溯 (以及儲存在暫存檔中的完整追溯)。

category

例外「類別」的描述，用於將例外轉換為字串（「類別：訊息」）。應在子類別中相應設定。

exception sphinx.errors.ConfigError

設定錯誤。

exception sphinx.errors.ExtensionError(message: str, orig_exc: Exception | None = None, modname: str | None = None)

擴充功能錯誤。

exception sphinx.errors.ThemeError

佈景主題錯誤。

exception sphinx.errors.VersionRequirementError

Sphinx 版本不相容錯誤。

上一頁

Sphinx API

下一頁

事件回呼 API