ユーティリティ¶

Sphinxは、拡張機能を開発するためのユーティリティクラスと関数を提供します。

コンポーネントの基本クラス¶

これらの基本クラスは、拡張機能がSphinxコンポーネント（例：Config、BuildEnvironmentなど）を簡単に取得できるようにするために役立ちます。

注釈

それらのサブクラスは、Sphinxと強く結合しているため、生のdocutilsでは動作しない場合があります。

class sphinx.transforms.SphinxTransform(document, startnode=None)[ソース]¶

Transformsの基本クラス。

docutils.transforms.Transformと比較して、このクラスはSphinx APIへのアクセスを向上させます。

property app: Sphinx¶: Sphinxオブジェクトへの参照。

property config: Config¶: Configオブジェクトへの参照。

property env: BuildEnvironment¶: BuildEnvironmentオブジェクトへの参照。

class sphinx.transforms.post_transforms.SphinxPostTransform(document, startnode=None)[ソース]¶

ポストトランスフォームの基本クラス。

ポストトランスフォームは、ドキュメントを出力用に再構築するために変更するために呼び出されます。それらは参照を解決し、画像を変換し、各出力形式に対して特別な変換などを行います。このクラスは、これらのポストトランスフォームの実装に役立ちます。

apply(**kwargs: Any) → None[ソース]¶: ドキュメントツリーにトランスフォームを適用するためにオーバーライドします。

is_supported() → bool[ソース]¶: 現在のビルダーでこのトランスフォームが動作するかどうかを確認します。

run(**kwargs: Any) → None[ソース]¶

ポストトランスフォームのメインメソッド。

サブクラスは、apply()の代わりにこのメソッドをオーバーライドする必要があります。

class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[ソース]¶

Sphinxディレクティブの基本クラス。

このクラスは、Sphinxディレクティブのヘルパーメソッドを提供します。

バージョン1.8で追加されました。

注釈

このクラスのサブクラスは、docutilsでは動作しない場合があります。このクラスはSphinxと強く結合しています。

get_location() → str[ソース]¶: ロギング用の現在の場所情報を取得します。

バージョン4.2で追加されました。

get_source_info() → tuple[str, int][ソース]¶: ソースと行番号を取得します。

バージョン3.0で追加されました。

parse_content_to_nodes(allow_section_headings: bool = False) → list[Node][ソース]¶

ディレクティブのコンテンツをノードに解析します。

パラメータ:: allow_section_headings – ディレクティブのコンテンツ内でタイトル (セクション) を許可するかどうか。このオプションは Docutils の doctree 構造の通常のチェックをバイパスすることに注意してください。このオプションを誤用すると、一貫性のない doctree につながる可能性があります。Docutils では、セクションノードは document、section、および sidebar ノードを含む Structural ノードの子ノードである必要があります。

バージョン 7.4 で追加。

parse_inline(text: str, *, lineno: int = -1) → tuple[list[Node], list[system_message]][ソース]¶

text をインライン要素として解析します。

パラメータ:

text – 解析するテキスト。単一行または段落である必要があります。これには構造要素 (見出し、トランジション、ディレクティブなど) を含めることはできません。
lineno – 解釈されたテキストが始まる行番号。

戻り値:

ノード (テキストとインライン要素) のリストと、system_message のリスト。

バージョン 7.4 で追加。

parse_text_to_nodes(text: str = '', /, *, offset: int = -1, allow_section_headings: bool = False) → list[Node][ソース]¶

text をノードに解析します。

パラメータ:

text – 文字列形式のテキスト。StringList も受け入れられます。
allow_section_headings – text 内でタイトル (セクション) を許可するかどうか。このオプションは Docutils の doctree 構造の通常のチェックをバイパスすることに注意してください。このオプションを誤用すると、一貫性のない doctree につながる可能性があります。Docutils では、セクションノードは document、section、および sidebar ノードを含む Structural ノードの子ノードである必要があります。
offset – コンテンツのオフセット。

バージョン 7.4 で追加。

set_source_info(node: Node) → None[ソース]¶: ノードにソースと行番号を設定します。

バージョン 2.1 で追加。

property config: Config¶: Configオブジェクトへの参照。

バージョン1.8で追加されました。

property env: BuildEnvironment¶: BuildEnvironmentオブジェクトへの参照。

バージョン1.8で追加されました。

class sphinx.util.docutils.SphinxRole[ソース]¶

Sphinx ロールの基本クラス。

このクラスは、Sphinx ロールのためのヘルパーメソッドを提供します。

バージョン 2.0 で追加。

注釈

このクラスのサブクラスは、docutilsでは動作しない場合があります。このクラスはSphinxと強く結合しています。

get_location() → str[ソース]¶: ロギング用の現在の場所情報を取得します。

バージョン4.2で追加されました。

property config: Config¶: Configオブジェクトへの参照。

バージョン 2.0 で追加。

content: Sequence[str]¶: 文字列のリスト。カスタマイズのためのディレクティブコンテンツです (「role」ディレクティブから)。

property env: BuildEnvironment¶: BuildEnvironmentオブジェクトへの参照。

バージョン 2.0 で追加。

inliner: Inliner¶: docutils.parsers.rst.states.Inliner オブジェクト。

lineno: int¶: 解釈されたテキストが始まる行番号。

name: str¶: ドキュメントで実際に使用されたロール名。

options: dict[str, Any]¶: カスタム設定のためのディレクティブオプションの辞書（「role」ディレクティブ由来）。

rawtext: str¶: 解釈されたテキスト入力全体を含む文字列。

text: str¶: 解釈されたテキストの内容。

class sphinx.util.docutils.ReferenceRole[ソース]¶

参照ロールの基底クラス。

参照ロールは、ロールのテキストとして link title <target> スタイルを受け入れることができます。解析された結果である、リンクのタイトルとターゲットは、self.title と self.target に保存されます。

バージョン 2.0 で追加。

disabled: bool¶: 参照が無効になっていることを示すブール値。

has_explicit_title: bool¶: ロールが明示的なタイトルを持っているかどうかを示すブール値。

target: str¶: 解釈されたテキストのリンクターゲット。

title: str¶: 解釈されたテキストのリンクタイトル。

class sphinx.transforms.post_transforms.images.ImageConverter(document, startnode=None)[ソース]¶

イメージコンバーターの基底クラス。

イメージコンバーターは、Docutils の変換モジュールの一種です。これは、ビルダーでサポートされていないイメージファイルを、そのビルダーに適した形式に変換するために使用されます。

たとえば、LaTeX ビルダー は、イメージ形式として PDF、PNG、および JPEG をサポートしています。ただし、SVG イメージはサポートしていません。このような場合、イメージコンバーターを使用すると、これらのサポートされていないイメージをドキュメントに埋め込むことができます。イメージコンバーターの1つである sphinx.ext.imgconverter は、内部で Imagemagick を使用して SVG イメージを PNG 形式に変換できます。

カスタムイメージコンバーターを作成するには、次の3つのステップがあります。

ImageConverter クラスのサブクラスを作成します。
conversion_rules、is_available()、および convert() をオーバーライドします。
Sphinx.add_post_transform() を使用して、イメージコンバーターを Sphinx に登録します。

convert(_from: str, _to: str) → bool[ソース]¶

イメージファイルを予期される形式に変換します。

_from はソースイメージファイルのパスであり、_to は出力先のファイルのパスです。

is_available() → bool[ソース]¶: イメージコンバーターが使用可能かどうかを返します。

available: bool | None = None¶: コンバーターが使用可能かどうか。ビルドの最初の呼び出し時に設定されます。結果は同じプロセス内で共有されます。

conversion_rules: list[tuple[str, str]] = []¶

イメージコンバーターがサポートする変換ルール。ソースイメージ形式（mimetype）と出力先のペアのリストとして表されます。

conversion_rules = [
    ('image/svg+xml', 'image/png'),
    ('image/gif', 'image/png'),
    ('application/pdf', 'image/png'),
]

default_priority = 200¶: この変換の数値的な優先度。0から999（オーバーライド）。

ユーティリティコンポーネント¶

class sphinx.events.EventManager(app: Sphinx)[ソース]¶

Sphinx のイベントマネージャー。

add(name: str) → None[ソース]¶: カスタム Sphinx イベントを登録します。

connect(name: Literal['config-inited'], callback: Callable[[Sphinx, Config], None], priority: int) → int[ソース]¶
connect(name: Literal['builder-inited'], callback: Callable[[Sphinx], None], priority: int) → int
connect(name: Literal['env-get-outdated'], callback: Callable[[Sphinx, BuildEnvironment, Set[str], Set[str], Set[str]], Sequence[str]], priority: int) → int
connect(name: Literal['env-before-read-docs'], callback: Callable[[Sphinx, BuildEnvironment, list[str]], None], priority: int) → int
connect(name: Literal['env-purge-doc'], callback: Callable[[Sphinx, BuildEnvironment, str], None], priority: int) → int
connect(name: Literal['source-read'], callback: Callable[[Sphinx, str, list[str]], None], priority: int) → int
connect(name: Literal['include-read'], callback: Callable[[Sphinx, Path, str, list[str]], None], priority: int) → int
connect(name: Literal['doctree-read'], callback: Callable[[Sphinx, nodes.document], None], priority: int) → int
connect(name: Literal['env-merge-info'], callback: Callable[[Sphinx, BuildEnvironment, list[str], BuildEnvironment], None], priority: int) → int
connect(name: Literal['env-updated'], callback: Callable[[Sphinx, BuildEnvironment], str], priority: int) → int
connect(name: Literal['env-get-updated'], callback: Callable[[Sphinx, BuildEnvironment], Iterable[str]], priority: int) → int
connect(name: Literal['env-check-consistency'], callback: Callable[[Sphinx, BuildEnvironment], None], priority: int) → int
connect(name: Literal['write-started'], callback: Callable[[Sphinx, Builder], None], priority: int) → int
connect(name: Literal['doctree-resolved'], callback: Callable[[Sphinx, nodes.document, str], None], priority: int) → int
connect(name: Literal['missing-reference'], callback: Callable[[Sphinx, BuildEnvironment, addnodes.pending_xref, nodes.TextElement], nodes.reference | None], priority: int) → int
connect(name: Literal['warn-missing-reference'], callback: Callable[[Sphinx, Domain, addnodes.pending_xref], bool | None], priority: int) → int
connect(name: Literal['build-finished'], callback: Callable[[Sphinx, Exception | None], None], priority: int) → int
connect(name: Literal['html-collect-pages'], callback: Callable[[Sphinx], Iterable[tuple[str, dict[str, Any], str]]], priority: int) → int
connect(name: Literal['html-page-context'], callback: Callable[[Sphinx, str, str, dict<
connect(name: Literal['linkcheck-process-uri'], callback: Callable[[Sphinx, str], str | None], priority: int) → int
connect(name: Literal['object-description-transform'], callback: Callable[[Sphinx, str, str, addnodes.desc_content], None], priority: int) → int
connect(name: Literal['autodoc-process-docstring'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], Sequence[str]], None], priority: int) → int
connect(name: Literal['autodoc-before-process-signature'], callback: Callable[[Sphinx, Any, bool], None], priority: int) → int
connect(name: Literal['autodoc-process-signature'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, dict[str, bool], str | None, str | None], tuple[str | None, str | None] | None], priority: int) → int
connect(name: Literal['autodoc-process-bases'], callback: Callable[[Sphinx, str, Any, dict[str, bool], list[str]], None], priority: int) → int
connect(name: Literal['autodoc-skip-member'], callback: Callable[[Sphinx, Literal['module', 'class', 'exception', 'function', 'method', 'attribute'], str, Any, bool, dict[str, bool]], bool], priority: int) → int
connect(name: Literal['todo-defined'], callback: Callable[[Sphinx, todo_node], None], priority: int) → int
connect(name: Literal['viewcode-find-source'], callback: Callable[[Sphinx, str], tuple[str, dict[str, tuple[Literal['class', 'def', 'other'], int, int]]]], priority: int) → int
connect(name: Literal['viewcode-follow-imported'], callback: Callable[[Sphinx, str, str], str | None], priority: int) → int
connect(name: str, callback: Callable[..., Any], priority: int) → int: 特定のイベントにハンドラーを接続します。

disconnect(listener_id: int) → None[source]¶

ハンドラーを接続解除します。

emit(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → list[source]¶

Sphinxイベントを発行します。

emit_firstresult(name: str, *args: Any, allowed_exceptions: tuple[type[Exception], ...] = ()) → Any[ソース]¶

Sphinxイベントを発行し、最初の結果を返します。

これは、Noneを返さない最初のハンドラーの結果を返します。

ユーティリティ関数¶

sphinx.util.parsing.nested_parse_to_nodes(state: RSTState, text: str | StringList, *, source: str = '<generated text>', offset: int = 0, allow_section_headings: bool = True, keep_title_context: bool = False) → list[Node][ソース]¶

text をノードに解析します。

パラメータ:

state – ステートマシンの状態。RSTStateのサブクラスである必要があります。

text – 文字列形式のテキスト。StringList も受け入れられます。

source – テキストのソース。新しいStringListを作成するときに使用します。

offset – コンテンツのオフセット。

allow_section_headings – text 内でタイトル (セクション) を許可するかどうか。このオプションは Docutils の doctree 構造の通常のチェックをバイパスすることに注意してください。このオプションを誤用すると、一貫性のない doctree につながる可能性があります。Docutils では、セクションノードは document、section、および sidebar ノードを含む Structural ノードの子ノードである必要があります。

keep_title_context – これがFalse（デフォルト）の場合、contentは独立したドキュメントであるかのように解析されます。つまり、タイトル装飾（例：下線）は周囲のドキュメントと一致する必要はありません。これは、解析されたコンテンツがドキュメント文字列など、まったく異なるコンテキストから来た場合に役立ちます。これがTrueの場合、タイトルの下線は周囲のドキュメントの下線と一致する必要があります。一致しない場合、動作は未定義になります。

バージョン 7.4 で追加。

ユーティリティ型¶

class sphinx.util.typing.ExtensionMetadata[ソース]¶

拡張機能のsetup()関数によって返されるメタデータ。

拡張機能のメタデータを参照してください。

env_version: int¶

拡張機能によって追加されたenvデータのバージョンを識別する整数。

parallel_read_safe: bool¶

ソースファイルの並列読み込みが拡張機能でサポートされているかどうかを示します。

parallel_write_safe: bool¶

出力ファイルの並列書き込みが拡張機能でサポートされているかどうかを示します（デフォルト：True）。

version: str¶

拡張機能のバージョン（デフォルト：'unknown version'）。

前へ

i18n API

次へ

テストAPI