Sphinx 增加的 Doctree 節點類別

用於特定領域物件描述的節點

頂層節點

這些節點構成物件描述的最頂層級。

class sphinx.addnodes.desc(rawsource='', *children, **attributes)

用於物件簽名列表以及它們的通用描述的節點。

包含一個或多個 desc_signature 節點，然後是一個單一的 desc_content 節點。

此節點始終有兩個類別

• 它所屬的領域的名稱，例如，py 或 cpp。

• 領域中物件類型的名稱，例如，function。

class sphinx.addnodes.desc_signature(*args: Any, **kwargs: Any)

用於單一物件簽名的節點。

預設情況下，簽名是單行簽名。設定 is_multiline = True 以描述多行簽名。在這種情況下，所有子節點都必須是 desc_signature_line 節點。

此節點始終具有類別 sig、sig-object 和它所屬的領域。

class sphinx.addnodes.desc_signature_line(rawsource='', text='', *children, **attributes)

用於多行物件簽名中的行的節點。

它應該僅用作 desc_signature 的子項，且 is_multiline 設定為 True。為應該取得永久連結的行設定 add_permalink = True。

class sphinx.addnodes.desc_content(rawsource='', *children, **attributes)

用於物件描述內容的節點。

必須是 desc 節點中的最後一個子節點。

class sphinx.addnodes.desc_inline(domain: str, *args: Any, **kwargs: Any)

用於行內文字中簽名片段的節點。

例如，這用於角色，如 cpp:expr。

此節點始終具有類別 sig、sig-inline 和它所屬領域的名稱。

用於簽名中高階結構的節點

這些節點出現在非多行 desc_signature 節點和 desc_signature_line 節點中。

class sphinx.addnodes.desc_name(*args: Any, **kwargs: Any)

用於主要物件名稱的節點。

例如，在 Python 類別 MyModule.MyClass 的宣告中，主要名稱是 MyClass。

此節點始終具有類別 sig-name。

class sphinx.addnodes.desc_addname(*args: Any, **kwargs: Any)

用於物件的其他名稱部分的節點。

例如，在 Python 類別 MyModule.MyClass 的宣告中，其他名稱部分是 MyModule.。

此節點始終具有類別 sig-prename。

class sphinx.addnodes.desc_type(rawsource='', text='', *children, **attributes)

用於傳回類型或物件類型名稱的節點。

class sphinx.addnodes.desc_returns(rawsource='', text='', *children, **attributes)

用於 “傳回” 註釋的節點（類似於 Python 中的 ->）。

class sphinx.addnodes.desc_parameterlist(rawsource='', text='', *children, **attributes)

用於通用參數列表的節點。

預設情況下，參數列表與簽名的其餘部分內嵌寫入。設定 multi_line_parameter_list = True 以描述多行參數列表。在這種情況下，每個參數都將寫在自己的縮排行上。如果 multi_line_trailing_comma 為 True，則會在最後一行新增一個尾隨逗號。

class sphinx.addnodes.desc_parameter(rawsource='', text='', *children, **attributes)

用於單一參數的節點。

class sphinx.addnodes.desc_optional(rawsource='', text='', *children, **attributes)

用於標記參數列表的可選部分的節點。

class sphinx.addnodes.desc_annotation(rawsource='', text='', *children, **attributes)

用於簽名註釋的節點（非 Python 3 風格註釋）。

用於簽名文字元素的節點

這些節點繼承 desc_sig_element，並且通常由 SigElementFallbackTransform 轉換為 docutils.nodes.inline。

擴充功能可能會建立額外的 desc_sig_* 類型的節點，但為了讓 SigElementFallbackTransform 將它們自動轉換為行內節點，它們必須透過 SIG_ELEMENTS 經由 desc_sig_element 的類別關鍵字引數 _sig_element=True 新增，例如：

class desc_custom_sig_node(desc_sig_element, _sig_element=True): ...

為了向後相容性，仍然可以使用 SIG_ELEMENTS.add(desc_custom_sig_node) 直接新增節點。

sphinx.addnodes.SIG_ELEMENTS: set[type[desc_sig_element]]

繼承 desc_sig_element 的類別集合。如果建置器的翻譯器類別未繼承自 SphinxTranslator，則每個節點類別都應由其處理。

此集合可以由第三方擴充功能手動擴充，或透過子類別化 desc_sig_element 並使用類別關鍵字引數 _sig_element=True 來擴充。

class sphinx.addnodes.desc_sig_element(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名行內文字節點的通用父類別。

class sphinx.addnodes.desc_sig_space(rawsource: str = '', text: str = ' ', *children: Element, **attributes: Any)

用於簽名中空格的節點。

class sphinx.addnodes.desc_sig_name(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

用於簽名中識別符的節點。

class sphinx.addnodes.desc_sig_operator(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

用於簽名中運算子的節點。

class sphinx.addnodes.desc_sig_punctuation(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

用於簽名中標點符號的節點。

class sphinx.addnodes.desc_sig_keyword(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名中通用關鍵字的節點。

class sphinx.addnodes.desc_sig_keyword_type(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名中作為內建型別的關鍵字節點。

class sphinx.addnodes.desc_sig_literal_number(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名中數值字面量的節點。

class sphinx.addnodes.desc_sig_literal_string(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名中字串字面量的節點。

class sphinx.addnodes.desc_sig_literal_char(rawsource: str = '', text: str = '', *children: Element, **attributes: Any)

簽名中字元字面量的節點。

新的提示類結構

class sphinx.addnodes.versionmodified(rawsource='', text='', *children, **attributes)

版本變更條目的節點。

目前用於 “versionadded”、“versionchanged”、“deprecated” 和 “versionremoved” 指令。

class sphinx.addnodes.seealso(rawsource='', *children, **attributes)

自訂 “另請參閱” 提示。

其他段落層級節點

class sphinx.addnodes.compact_paragraph(rawsource='', text='', *children, **attributes)

用於緊湊段落的節點（永遠不會產生 <p> 節點）。

新的行內節點

class sphinx.addnodes.index(rawsource='', text='', *children, **attributes)

索引條目的節點。

此節點由 index 指令建立，並具有一個屬性 entries。其值為 5 元組的列表，格式為 (entrytype, entryname, target, ignored, key)。

entrytype 是 “single”、“pair”、“double”、“triple” 之一。

key 是通用索引頁面的分類字元（通常為單個字元）。有關詳細資訊，另請參閱：glossary 和 https://github.com/sphinx-doc/sphinx/pull/2320。

class sphinx.addnodes.pending_xref(rawsource='', *children, **attributes)

用於跨參照的節點，這些跨參照在沒有關於所有文件的完整資訊時無法解析。

這些節點在寫入輸出之前，在 BuildEnvironment.resolve_references 中解析。

class sphinx.addnodes.pending_xref_condition(rawsource='', text='', *children, **attributes)

節點表示建立跨參照的潛在方式以及應使用此方式的條件。

此節點僅允許放置在 pending_xref 節點下。 pending_xref 節點必須不包含 pending_xref_condition 節點，或者必須僅包含 pending_xref_condition 節點。

跨參照解析器將包含 pending_xref_condition 節點的 pending_xref 替換為這些 pending_xref_condition 節點內容之一的內容。它使用 condition 屬性來決定要使用哪個 pending_xref_condition 節點的內容。例如，讓我們考慮跨參照解析器如何作用於

<pending_xref refdomain="py" reftarget="io.StringIO ...>
    <pending_xref_condition condition="resolved">
        <literal>
            StringIO
    <pending_xref_condition condition="*">
        <literal>
            io.StringIO

如果跨參照解析器成功解析跨參照，則它將 pending_xref 重寫為

<reference>
    <literal>
        StringIO

否則，如果跨參照解析失敗，它將 pending_xref 重寫為

<reference>
    <literal>
        io.StringIO

pending_xref_condition 節點應具有 condition 屬性。網域可以將其個別條件儲存在屬性中，以在解析階段篩選內容。作為保留的條件名稱，condition="*" 用於解析失敗的回退。此外，作為推薦的條件名稱，condition="resolved" 代表 intersphinx 模組中的解析成功。

在 4.0 版本中新增。

class sphinx.addnodes.literal_emphasis(rawsource='', text='', *children, **attributes)

行為類似 emphasis 的節點，但不會套用進一步的文字處理器（例如 HTML 輸出的 smartypants）。

class sphinx.addnodes.download_reference(rawsource='', text='', *children, **attributes)

用於下載參考的節點，類似於 pending_xref。

特殊節點

class sphinx.addnodes.only(rawsource='', *children, **attributes)

用於 “only” 指令的節點（基於標籤的條件式包含）。

class sphinx.addnodes.highlightlang(rawsource='', *children, **attributes)

插入以設定後續程式碼區塊的醒目顯示語言和行號選項。

您應該不需要在擴充功能中產生以下節點。

class sphinx.addnodes.glossary(rawsource='', *children, **attributes)

插入詞彙表的節點。

class sphinx.addnodes.toctree(rawsource='', *children, **attributes)

用於插入 “TOC 樹狀結構” 的節點。

class sphinx.addnodes.start_of_file(rawsource='', *children, **attributes)

用於標記新檔案開頭的節點，僅在 LaTeX 建置器中使用。

class sphinx.addnodes.productionlist(rawsource='', *children, **attributes)

用於語法產生式列表的節點。

包含 production 節點。

class sphinx.addnodes.production(rawsource='', text='', *children, **attributes)

用於單個語法產生規則的節點。

Previous

Parser API

Next

Logging API