事件回呼 API

將回呼函式連接到事件是一種擴充 Sphinx 的簡單方法，透過在各個點掛鉤到建構流程中。

在擴充功能的 setup 函式中，或是在您的專案 conf.py 中的 setup 函式中使用 Sphinx.connect()，以將函式連接到事件

def source_read_handler(app, docname, source):
    print('do something here...')

def setup(app):
    app.connect('source-read', source_read_handler)

另請參閱

擴充功能可以使用 Sphinx.add_event() 新增它們自己的事件，並使用 Sphinx.emit() 或 Sphinx.emit_firstresult() 呼叫它們。

核心事件概觀

以下是建構期間發生的核心事件概觀。

1. event.config-inited(app,config)
2. event.builder-inited(app)
3. event.env-get-outdated(app, env, added, changed, removed)
4. event.env-before-read-docs(app, env, docnames)

for docname in docnames:
   5. event.env-purge-doc(app, env, docname)

   if doc changed and not removed:
      6. source-read(app, docname, source)
      7. run source parsers: text -> docutils.document
         - parsers can be added with the app.add_source_parser() API
         - event.include-read(app, relative_path, parent_docname, content)
           is called for each include directive
      8. apply transforms based on priority: docutils.document -> docutils.document
         - event.doctree-read(app, doctree) is called in the middle of transforms,
           transforms come before/after this event depending on their priority.

9. event.env-merge-info(app, env, docnames, other)
   - if running in parallel mode, this event will be emitted for each process

10. event.env-updated(app, env)
11. event.env-get-updated(app, env)

if environment is written to disk:
   12. event.env-check-consistency(app, env)

13. event.write-started(app, builder)
    - This is called after ``app.parallel_ok`` has been set,
      which must not be altered by any event handler.

# The updated-docs list can be builder dependent, but generally includes all new/changed documents,
# plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
# For builders that output a single page, they are first joined into a single doctree before post-transforms
# or the doctree-resolved event is emitted
for docname in updated-docs:
   14. apply post-transforms (by priority): docutils.document -> docutils.document
   15. event.doctree-resolved(app, doctree, docname)
       - In the event that any reference nodes fail to resolve, the following may emit:
       - event.missing-reference(env, node, contnode)
       - event.warn-missing-reference(domain, node)

16. Generate output files
17. event.build-finished(app, exception)

以下也是事件流程圖，在 Sphinx 建構流程的背景下

Sphinx 核心事件流程

核心事件詳細資訊

以下是這些事件的更詳細列表。

config-inited(app, config)

參數:

• app – Sphinx

• config – Config

當 config 物件已初始化時發出。

在版本 1.8 中新增。

builder-inited(app)

參數:

app – Sphinx

當建構器物件已建立時發出（可作為 app.builder 使用）。

env-get-outdated(app, env, added, changed, removed)

參數:

• app – Sphinx

• env – BuildEnvironment

• added – Set[str]

• changed – Set[str]

• removed – Set[str]

傳回值:

要重新讀取的額外 docname 的 Sequence[str]

當環境判斷哪些來源檔案已變更且應重新讀取時發出。added、changed 和 removed 是環境已判定的 docname 集合。您可以傳回要重新讀取的 docname 列表，以添加到這些列表中。

在版本 1.1 中新增。

env-purge-doc(app, env, docname)

參數:

• app – Sphinx

• env – BuildEnvironment

• docname – str

當應從環境中清除來源檔案的所有追蹤時發出，也就是說，如果來源檔案被移除或在重新讀取之前。這是為了在環境屬性中保留自己快取的擴充功能。

例如，環境中存在所有模組的快取。當來源檔案已變更時，檔案的快取條目會被清除，因為模組宣告可能已從檔案中移除。

在版本 0.5 中新增。

env-before-read-docs(app, env, docnames)

參數:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

在環境判定所有新增和變更檔案的列表之後，並在讀取它們之前發出。它允許擴充功能作者在處理之前重新排序 docname 列表（就地），或新增 Sphinx 未考慮變更的更多 docname（但永遠不要新增任何不在 found_docs 中的 docname）。

您也可以移除文件名稱；請謹慎執行此操作，因為這會讓 Sphinx 將變更的檔案視為未變更。

在版本 1.3 中新增。

source-read(app, docname, content)

參數:

• app – Sphinx

• docname – str

• content – 包含單個元素的 list[str]，表示包含檔案的內容。

當來源檔案已被讀取時發出。

您可以處理 content 並替換此項目以實作來源層級轉換。

例如，如果您想要像 LaTeX 中一樣使用 $ 符號來分隔行內數學式，您可以使用正規表示式將 $...$ 替換為 :math:`...`。

在版本 0.5 中新增。

include-read(app, relative_path, parent_docname, content)

參數:

• app – Sphinx

• relative_path – Path，表示相對於來源目錄的包含檔案。

• parent_docname – 包含 include 指令的文件名稱的 str。

• content – 包含單個元素的 list[str]，表示包含檔案的內容。

當使用 include 指令讀取檔案時發出。

您可以處理 content 並替換此項目以轉換包含的內容，就像 source-read 事件一樣。

在版本 7.2.5 中新增。

另請參閱

include 指令與 source-read 事件。

object-description-transform(app, domain, objtype, contentnode)

參數:

• app – Sphinx

• domain – str

• objtype – str

• contentnode – desc_content

當物件描述指令已執行時發出。domain 和 objtype 參數是表示物件描述的字串。而 contentnode 是物件的內容。它可以就地修改。

在版本 2.4 中新增。

doctree-read(app, doctree)

參數:

• app – Sphinx

• doctree – docutils.nodes.document

當 doctree 已由環境剖析和讀取，且即將被 pickle 時發出。doctree 可以就地修改。

missing-reference(app, env, node, contnode)

參數:

• app – Sphinx

• env – BuildEnvironment

• node – 要解析的 pending_xref 節點。它的 reftype、reftarget、modname 和 classname 屬性決定了參照的類型和目標。

• contnode – 攜帶未來參照內部的文字和格式，並且應該是傳回的參照節點的子節點。

傳回值:

要插入到文件樹中以取代節點的新節點，或 None 以讓其他處理常式嘗試。

當無法解析對物件的交叉參照時發出。如果事件處理常式可以解析參照，它應該傳回一個新的 docutils 節點，以插入到文件樹中以取代節點 node。通常，此節點是一個包含 contnode 作為子節點的 reference 節點。如果處理常式無法解析交叉參照，它可以傳回 None 以讓其他處理常式嘗試，或引發 NoUri 以防止其他處理常式嘗試並抑制關於此交叉參照未解析的警告。

在版本 0.5 中新增。

warn-missing-reference(app, domain, node)

參數:

• app – Sphinx

• domain – 遺失參照的 Domain。

• node – 無法解析的 pending_xref 節點。

傳回值:

如果發出警告，則為 True，否則為 None

當即使在 missing-reference 之後也無法解析對物件的交叉參照時發出。如果事件處理常式可以針對遺失的參照發出警告，它應該傳回 True。組態變數 nitpick_ignore 和 nitpick_ignore_regex 防止針對相應的節點發出事件。

在版本 3.4 中新增。

doctree-resolved(app, doctree, docname)

參數:

• app – Sphinx

• doctree – docutils.nodes.document

• docname – str

當 doctree 已被環境「解析」，也就是說，所有參照都已解析，並且 TOC 已插入時發出。doctree 可以就地修改。

這裡是要替換在寫入器中沒有訪問器方法的自訂節點的位置，以便它們在寫入器遇到它們時不會導致錯誤。

env-merge-info(app, env, docnames, other)

參數:

• app – Sphinx

• env – BuildEnvironment

• docnames – list[str]

• other – BuildEnvironment

此事件僅在啟用文件的平行讀取時發出。它針對每個已讀取某些文件的子程序發出一次。

您必須在擴充功能中處理此事件，該擴充功能將資料儲存在環境中的自訂位置。否則，主程序中的環境將不會知道儲存在子程序中的資訊。

other 是來自子程序的環境物件，env 是來自主程序的環境。docnames 是子程序中已讀取的文件名稱集合。

在版本 1.3 中新增。

env-updated(app, env)

參數:

• app – Sphinx

• env – BuildEnvironment

傳回值:

str 的可迭代物件

在讀取所有文件之後，當環境和所有 doctree 現在都是最新的時發出。

您可以從處理常式傳回 docname 的可迭代物件。然後這些文件將被視為已更新，並將在寫入階段期間被（重新）寫入。

在版本 0.5 中新增。

在版本 1.3 中變更: 現在使用處理常式的傳回值。

env-get-updated(app, env)

參數:

• app – Sphinx

• env – BuildEnvironment

傳回值:

str 的可迭代物件

當環境判斷哪些來源檔案已變更且應重新讀取時發出。您可以傳回要重新讀取的 docname 的可迭代物件。

env-check-consistency(app, env)

參數:

• app – Sphinx

• env – BuildEnvironment

當一致性檢查階段時發出。您可以檢查整個文件元資料的一致性。

在版本 1.6 中新增。

write-started(app, builder)

參數:

• app – Sphinx

• builder – Builder

在建構器開始解析和寫入文件之前發出。

在版本 7.4 中新增。

build-finished(app, exception)

參數:

• app – Sphinx

• exception – Exception 或 None

當建構已完成，在 Sphinx 退出之前發出，通常用於清理。即使建構流程引發例外狀況，也會發出此事件，以 exception 參數給出。在事件處理常式執行後，例外狀況會在應用程式中重新引發。如果建構流程未引發例外狀況，exception 將為 None。這允許根據例外狀況狀態自訂清理動作。

在版本 0.5 中新增。

建構器特定事件

這些事件由特定的建構器發出。

html-collect-pages(app)

參數:

app – Sphinx

傳回值:

(pagename, context, templatename) 的可迭代物件，其中 pagename 和 templatename 是字串，而 context 是 dict[str, Any]。

當 HTML 建構器開始寫入非文件頁面時發出。

您可以透過從此事件傳回可迭代物件來新增要寫入的頁面。

在版本 1.0 中新增。

html-page-context(app, pagename, templatename, context, doctree)

參數:

• app – Sphinx

• pagename – str

• templatename – str

• context – dict[str, Any]

• doctree – docutils.nodes.document 或 None

傳回值:

str 或 None

當 HTML 建構器已建立用於呈現範本的內容字典時發出 – 這可以用於將自訂元素新增到內容中。

pagename 參數是要呈現頁面的標準名稱，也就是說，沒有 .html 後綴並使用斜線作為路徑分隔符。templatename 是要呈現的範本名稱，對於來自 reStructuredText 文件中的所有頁面，這將是 'page.html'。

context 參數是一個值字典，這些值會提供給範本引擎以呈現頁面，並且可以修改以包含自訂值。

當頁面是從 reStructuredText 文件建立時，doctree 參數將是 doctree；當頁面僅從 HTML 範本建立時，它將是 None。

您可以從處理常式傳回字串，然後它將取代 'page.html' 作為此頁面的 HTML 範本。

提示

您可以透過 Sphinx.add_js_file() 和 Sphinx.add_css_file() (自 v3.5.0 起) 為特定頁面安裝 JS/CSS 檔案。

在版本 0.4 中新增。

在版本 1.3 中變更: 傳回值現在可以指定範本名稱。

linkcheck-process-uri(app, uri)

參數:

• app – Sphinx

• uri – 收集到的 URI 的 str

傳回值:

str 或 None

當 linkcheck 建構器從文件中收集超連結時發出。

事件處理常式可以透過傳回字串來修改 URI。

在版本 4.1 中新增。

上一頁

應用程式 API

下一頁

專案 API