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

options および content パラメータは、role ディレクティブを介して作成されたカスタムロールでのみ使用されます。戻り値は、2 つのリストのタプルであり、最初のリストにはロールからのテキストノードと要素が含まれ、2 番目のリストには生成されたシステムメッセージが含まれます。詳細については、Docutils のカスタムロールの概要を参照してください。

カスタムロールの作成¶

Sphinx は、カスタムロールを作成するための 2 つの基本クラス、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[source]¶

新しいディレクティブのマークアップ構文は、次の 5 つのクラス属性によって決定されます。

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()[source]¶: このメソッドは、ディレクティブの引数、オプション、およびコンテンツを処理し、ディレクティブが検出された場所でドキュメントツリーに挿入される 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 を使用します。

最初のメソッドはディレクティブのすべてのコンテンツをマークアップとして解析し、2 番目のメソッドは指定された 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() を使用します。これは、1 行または段落であり、構造要素 (見出し、トランジション、ディレクティブなど) を含まないテキストにのみ使用する必要があります。

注意

sphinx.util.docutils.switch_source_input() を使用すると、ディレクティブでコンテンツを解析するときにソース (入力) ファイルを変更できます。これは、sphinx.ext.autodoc のように、ドキュメント文字列を解析するために使用される混在コンテンツを解析する場合に役立ちます。

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 クラスで表現し、これは docutils.statemachine モジュールの両方で ViewList から継承されます。これは拡張された機能を持つリストであり、スライスが元のリストのビューを作成することや、リストにソース行番号に関する情報が含まれていることなどが含まれます。

Directive.content 属性は StringList です。reStructuredTextとして解析されるコンテンツを生成する場合、Docutils APIのために StringList を作成する必要があります。Sphinxが提供するユーティリティ関数はこれを自動的に処理します。コンテンツ生成において重要な点は以下の通りです。

ViewList コンストラクタは、文字列のリスト（行）とソース（ドキュメント）名を受け取ります。
ViewList.append() メソッドは、行とソース名も受け取ります。