Domain API

class sphinx.domains.Domain(env: BuildEnvironment)

Domain 旨在作為一組「物件」描述指令，用於描述性質相似的物件，以及對應的角色以建立對它們的參考。範例包括 Python 模組、類別、函式等、範本語言的元素、Sphinx 角色和指令等。

每個 domain 都有一個獨立的儲存空間，用於儲存有關現有物件以及如何在 self.data 中參考它們的資訊，self.data 必須是一個字典。它還必須實作多個函式，以統一的方式向 Sphinx 的各個部分公開物件資訊，以允許使用者以與 domain 無關的方式參考或搜尋物件。

關於 self.data：由於所有物件和交叉參考資訊都儲存在 BuildEnvironment 實例上，因此 domain.data 物件也儲存在 env.domaindata 字典中，鍵為 domain.name。在建置過程開始之前，每個活動的 domain 都會被實例化並給予環境物件；domaindata 字典必須不存在，或者是一個字典，其 ‘version’ 鍵等於 domain 類別的 data_version 屬性。否則，會引發 OSError，並且會丟棄 pickled 環境。

add_object_type(name: str, objtype: ObjType) → None

新增物件類型。

check_consistency() → None

執行一致性檢查 (實驗性)。

clear_doc(docname: str) → None

移除 domain 特定索引中文件的蹤跡。

directive(name: str) → type[Directive] | None

傳回指令適配器類別，該類別始終將已註冊指令的完整名稱 (‘domain:name’) 作為 self.name 給出。

get_enumerable_node_type(node: Node) → str | None

取得可列舉節點的類型 (實驗性)。

get_full_qualified_name(node: Element) → str | None

傳回給定節點的完整限定名稱。

get_objects() → Iterable[tuple[str, str, str, str, str, int]]

傳回「物件描述」的可迭代物件。

物件描述是包含六個項目的元組

name

完整限定名稱。

dispname

搜尋/連結時顯示的名稱。

type

物件類型，self.object_types 中的索引鍵。

docname

要找到它的文件。

anchor

物件的錨點名稱。

priority

物件的「重要性」(決定在搜尋結果中的位置)。以下之一

1

預設優先順序 (放置在全文檢索比對之前)。

0

物件很重要 (放置在預設優先順序物件之前)。

2

物件不重要 (放置在全文檢索比對之後)。

-1

物件完全不應顯示在搜尋中。

get_type_name(type: ObjType, primary: bool = False) → str

傳回給定 ObjType 的完整名稱。

merge_domaindata(docnames: Set[str], otherdata: dict[str, Any]) → None

從不同的 domaindata 索引 (來自平行建置中的子程序) 合併關於 docnames 的資料。

process_doc(env: BuildEnvironment, docname: str, document: nodes.document) → None

在環境讀取文件後處理文件。

process_field_xref(pnode: pending_xref) → None

處理在文件欄位中建立的 pending xref。例如，附加有關目前範圍的資訊。

resolve_any_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) → list[tuple[str, nodes.reference]]

使用給定的 target 解析 pending_xref node。

參考來自 “any” 或類似的角色，這表示我們不知道類型。否則，引數與 resolve_xref() 的引數相同。

此方法必須傳回元組 ('domain:role', newnode) 的清單 (可能為空)，其中 'domain:role' 是可能已建立相同參考的角色名稱，例如 'py:func'。newnode 是 resolve_xref() 將傳回的內容。

在 1.3 版本中新增。

resolve_xref(env: BuildEnvironment, fromdocname: str, builder: Builder, typ: str, target: str, node: pending_xref, contnode: Element) → nodes.reference | None

使用給定的 typ 和 target 解析 pending_xref node。

此方法應傳回一個新節點，以取代 xref 節點，其中包含作為交叉參考標記內容的 contnode。

如果找不到解析，則可以傳回 None；然後 xref 節點將給予 missing-reference 事件，如果該事件沒有產生解析，則替換為 contnode。

此方法也可以引發 sphinx.environment.NoUri 以抑制發出 missing-reference 事件。

role(name: str) → RoleFunction | None

傳回角色適配器函式，該函式始終將已註冊角色的完整名稱 (‘domain:name’) 作為第一個引數給出。

setup() → None

設定 domain 物件。

dangling_warnings: dict[str, str] = {}

角色名稱 -> 參考遺失時的警告訊息

data: dict[str, Any]

資料值

data_version = 0

資料版本，當 self.data 的格式變更時增加此版本

directives: dict[str, type[Directive]] = {}

指令名稱 -> 指令類別

enumerable_nodes: dict[type[Node], tuple[str, TitleGetter | None]] = {}

node_class -> (enum_node_type, title_getter)

indices: list[type[Index]] = []

Index 子類別的清單

initial_data: dict[str, Any] = {}

全新環境的資料值

label = ''

domain 標籤：更長、更具描述性 (用於訊息)

name = ''

domain 名稱：應簡短但唯一

object_types: dict[str, ObjType] = {}

類型 (通常是指令) 名稱 -> ObjType 實例

roles: dict[str, RoleFunction | XRefRole] = {}

角色名稱 -> 角色可調用項

class sphinx.domains.ObjType(lname: str, /, *roles: Any, **attrs: Any)

ObjType 是用於描述網域可以記錄的文件物件類型的描述。在 Domain 子類別的 object_types 屬性中，物件類型名稱會對應到此類別的實例。

建構子參數

• lname: 類型的本地化名稱 (請勿包含網域名稱)

• roles: 所有可以參照此類型物件的角色

• attrs: 物件屬性 – 目前僅知 “searchprio”，其定義物件在全文檢索索引中的優先順序，請參閱 Domain.get_objects()。

class sphinx.domains.Index(domain: Domain)

Index 是用於描述特定網域索引的描述。若要將索引新增至網域，請繼承 Index，覆寫三個名稱屬性

• name 是用於產生檔案名稱的識別符。它也用於索引的超連結目標。因此，使用者可以使用 ref 角色和字串來參照索引頁面，該字串結合了網域名稱和 name 屬性 (例如 :ref:`py-modindex`)。

• localname 是索引的章節標題。

• shortname 是索引的簡短名稱，用於 HTML 輸出中的關聯列。可以為空以停用關聯列中的項目。

並提供 generate() 方法。然後，將索引類別新增至網域的 indices 列表。擴充功能可以使用 add_index_to_domain() 將索引新增至現有網域。

變更於 3.0 版本: 索引頁面可以透過網域名稱和索引名稱，經由 ref 角色來參照。

abstractmethod generate(docnames: Iterable[str] | None = None) → tuple[list[tuple[str, list[IndexEntry]]], bool]

取得索引的項目。

如果給定 docnames，則限制為參照這些文件名稱的項目。

傳回值為 (content, collapse) 的 tuple

collapse

一個布林值，決定子項目是否應以摺疊狀態開始 (適用於支援摺疊子項目的輸出格式)。

content:

一個 (letter, entries) tuple 序列，其中 letter 是給定 entries 的「標題」，通常是起始字母，而 entries 是單個項目的序列。每個項目都是一個 IndexEntry。

class sphinx.domains.IndexEntry(name: str, subtype: int, docname: str, anchor: str, extra: str, qualifier: str, descr: str)

索引項目。

注意

qualifier 和 description 並不會針對某些輸出格式 (例如 LaTeX) 進行呈現。

name: str

要顯示的索引項目名稱。

subtype: int

子項目相關類型。以下其中之一

0

一般項目。

1

具有子項目的項目。

2

子項目。

docname: str

項目所在的 docname。

anchor: str

docname 內項目的錨點

extra: str

項目的額外資訊。

qualifier: str

描述的限定詞。

descr: str

項目的描述。

class sphinx.directives.ObjectDescription(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)

用於描述類別、函式或類似物件的指令。

不會直接使用，而是子類別化 (在特定網域的指令中) 以新增自訂行為。

_object_hierarchy_parts(sig_node: desc_signature) → tuple[str, ...]

傳回字串的 tuple，物件階層的每個部分一個項目 (例如 ('module', 'submodule', 'Class', 'method'))。傳回的 tuple 用於在目錄中正確地將子項目巢狀於父項目內，並且也可以在 _toc_entry_name() 方法中使用。

此方法不得在目錄產生之外使用。

_toc_entry_name(sig_node: desc_signature) → str

傳回物件的目錄項目的文字。

此函式在 run() 中呼叫一次，以設定目錄項目的名稱 (在物件節點上設定一個特殊的屬性 _toc_name，稍後在 environment.collectors.toctree.TocTreeCollector.process_doc().build_toc() 中收集目錄項目時使用)。

為了支援物件的目錄項目，網域必須覆寫此方法，同時也要遵守組態設定 toc_object_entries_show_parents。網域也必須覆寫 _object_hierarchy_parts()，物件階層的每個部分有一個 (字串) 項目。此方法的結果會設定在簽名節點上，並且可以作為 sig_node['_toc_parts'] 存取，以在此方法中使用。產生的 tuple 也用於在目錄中正確地將子項目巢狀於父項目內。

此方法的範例實作位於 python 網域 (PyObject._toc_entry_name()) 中。python 網域會在 handle_signature() 方法中設定 _toc_parts 屬性。

add_target_and_index(name: ObjDescT, sig: str, signode: desc_signature) → None

如果適用，將交叉參照 ID 和項目新增至 self.indexnode。

name 是 handle_signature() 傳回的任何內容。

after_content() → None

在剖析內容後呼叫。

用於重設建置環境中目前指令內容的相關資訊。

before_content() → None

在剖析內容之前呼叫。

用於設定建置環境中目前指令內容的相關資訊。

get_signatures() → list[str]

從指令引數中擷取要記錄的文件簽名。

預設情況下，簽名是以引數形式給定，每行一個。

handle_signature(sig: str, signode: desc_signature) → ObjDescT

剖析簽名 sig。

然後將個別節點附加到 signode。如果引發 ValueError，則剖析中止，並將整個 sig 放入單個 desc_name 節點中。

傳回值應為識別物件的值。它會未經更改地傳遞至 add_target_and_index()，否則僅用於跳過重複項。

run() → list[Node]

主要指令進入函式，在 docutils 遇到指令時呼叫。

此指令旨在非常容易子類別化，因此它委派給幾個額外的方法。它的作用是

• 找出是否作為特定網域的指令呼叫，設定 self.domain

• 建立一個 desc 節點以容納所有內部的描述

• 剖析標準選項，目前為 no-index

• 在需要時建立索引節點作為 self.indexnode

• 使用 self.handle_signature() 剖析所有給定的簽名 (由 self.get_signatures() 傳回)，這應該傳回名稱或引發 ValueError

• 使用 self.add_target_and_index() 新增索引項目

• 剖析內容並處理其中的文件欄位

transform_content(content_node: desc_content) → None

可用於操作內容。

在透過巢狀剖析建立內容之後，但在發出 object-description-transform 事件之前，以及在資訊欄位轉換之前呼叫。

final_argument_whitespace = True

最後一個引數可以包含空格嗎？

has_content = True

指令可以有內容嗎？

option_spec: ClassVar[OptionSpec] = {'no-contents-entry': <function flag>, 'no-index': <function flag>, 'no-index-entry': <function flag>, 'no-typesetting': <function flag>, 'nocontentsentry': <function flag>, 'noindex': <function flag>, 'noindexentry': <function flag>}

選項名稱到驗證器函式的映射。

optional_arguments = 0

必要引數後面的選用引數數量。

required_arguments = 1

必要指令引數的數量。

Python 網域

class sphinx.domains.python.PythonDomain(env: BuildEnvironment)

Python 語言網域。

objects

modules

note_object(name: str, objtype: str, node_id: str, aliased: bool = False, location: Any = None) → None

記錄 Python 物件以進行交叉參照。

在 2.1 版本中新增。

note_module(name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) → None

記錄 Python 模組以進行交叉參照。

在 2.1 版本中新增。

上一頁

Docutils 標記 API

下一頁

剖析器 API