Docutils 標記 API¶

本節描述用於新增 reStructuredText 標記元素 (角色與指令) 的 API。

角色¶

角色遵循以下描述的介面。它們必須透過擴充功能使用 Sphinx.add_role() 或 Sphinx.add_role_to_domain() 註冊。

def role_function(
    role_name: str, raw_source: str, text: str,
    lineno: int, inliner: Inliner,
    options: dict = {}, content: list = [],
) -> tuple[list[Node], list[system_message]]:
    elements = []
    messages = []
    return elements, messages

選項與內容參數僅用於透過 role 指令建立的自訂角色。傳回值為包含兩個列表的元組，第一個列表包含來自角色的文字節點與元素，第二個列表包含任何產生的系統訊息。如需更多資訊，請參閱 Docutils 的自訂角色概觀。

建立自訂角色¶

Sphinx 提供兩個用於建立自訂角色的基底類別：SphinxRole 與 ReferenceRole。

這些類別為建立角色提供基於類別的介面，主要邏輯必須在您的 run() 方法中實作。這些類別提供許多有用的方法與屬性，例如 self.text、self.config 與 self.env。ReferenceRole 類別實作 Sphinx 的 title <target> 邏輯，公開 self.target 與 self.title 屬性。這對於建立交叉參考角色很有用。

指令¶

指令由衍生自 docutils.parsers.rst.Directive 的類別處理。它們必須透過擴充功能使用 Sphinx.add_directive() 或 Sphinx.add_directive_to_domain() 註冊。

class docutils.parsers.rst.Directive[原始碼]¶

新指令的標記語法由以下五個類別屬性決定

required_arguments = 0¶: 必要指令引數的數量。

optional_arguments = 0¶: 必要引數後選用引數的數量。

final_argument_whitespace = False¶: 最後一個引數可以包含空白字元嗎？

option_spec = None¶

選項名稱到驗證器函式的對應。

選項驗證器函式接受單一參數，即選項引數 (或未給定時的 None)，且應驗證它或將其轉換為正確的格式。它們會引發 ValueError 或 TypeError 以指示失敗。

在 docutils.parsers.rst.directives 模組中有幾個預定義且可能很有用的驗證器。

has_content = False¶: 指令可以有內容嗎？

新指令必須實作 run() 方法

run()[原始碼]¶: 此方法必須處理指令引數、選項與內容，並傳回 Docutils/Sphinx 節點的列表，這些節點將插入到文件中指令遇到的位置。

始終在指令上設定的實例屬性為

name¶: 指令名稱 (在以多個名稱註冊相同指令類別時很有用)。

arguments¶: 給定指令的引數，以列表形式呈現。

options¶: 給定指令的選項，以字典形式呈現，將選項名稱對應到已驗證/轉換的值。

content¶: 指令內容 (如果有的話)，以 ViewList 形式呈現。

lineno¶: 指令出現所在的絕對行號。這不一定是有用的值；請改用 srcline。

content_offset¶: 指令內容的內部偏移量。在呼叫 nested_parse 時使用 (請參閱下文)。

block_text¶: 包含整個指令的字串。

state¶
state_machine¶: 控制剖析的狀態與狀態機。用於 nested_parse。

另請參閱

建立指令 Docutils 文件的 HOWTO

將指令內容解析為 reStructuredText¶

許多指令將包含更多必須剖析的標記。若要執行此操作，請使用 run() 方法中的下列 API 之一

第一個方法將指令的所有內容剖析為標記，而第二個方法僅剖析給定的 text 字串。兩種方法都會在列表中傳回已剖析的 Docutils 節點。

這些方法的使用方式如下

def run(self) -> list[Node]:
    # either
    parsed = self.parse_content_to_nodes()
    # or
    parsed = self.parse_text_to_nodes('spam spam spam')
    return parsed

注意

上述公用程式方法已在 Sphinx 7.4 中新增。在 Sphinx 7.4 之前，應使用下列方法來剖析內容

self.state.nested_parse
sphinx.util.nodes.nested_parse_with_titles() – 這允許已剖析內容中的標題。

def run(self) -> list[Node]:
    container = docutils.nodes.Element()
    # either
    nested_parse_with_titles(self.state, self.result, container)
    # or
    self.state.nested_parse(self.result, 0, container)
    parsed = container.children
    return parsed

若要剖析行內標記，請使用 parse_inline()。這僅適用於單行或段落的文字，且不包含任何結構元素 (標題、轉場、指令等)。

注意

sphinx.util.docutils.switch_source_input() 允許在指令中剖析內容期間變更來源 (輸入) 檔案。它對於剖析混合內容很有用，例如在 sphinx.ext.autodoc 中，它用於剖析 docstring。

from sphinx.util.docutils import switch_source_input
from sphinx.util.parsing import nested_parse_to_nodes

# Switch source_input between parsing content.
# Inside this context, all parsing errors and warnings are reported as
# happened in new source_input (in this case, ``self.result``).
with switch_source_input(self.state, self.result):
    parsed = nested_parse_to_nodes(self.state, self.result)

在 1.7 版本中已棄用：在 Sphinx 1.6 之前，sphinx.ext.autodoc.AutodocReporter 用於此目的。它已被 switch_source_input() 取代。

ViewLists 與 StringLists¶

Docutils 在 StringList 類別中表示文件原始碼行，該類別繼承自 ViewList，兩者都在 docutils.statemachine 模組中。這是一個具有擴充功能的列表，包括切片會建立原始列表的檢視，且該列表包含有關原始碼行號的資訊。

Directive.content 屬性是 StringList。如果您產生要剖析為 reStructuredText 的內容，則必須為 Docutils API 建立 StringList。Sphinx 提供的公用程式函式會自動處理此問題。對於內容產生而言，以下幾點很重要

ViewList 建構子接受字串 (行) 列表與來源 (文件) 名稱。
ViewList.append() 方法也接受行與來源名稱。