ユーティリティ

Sphinxには拡張開発のためのユーティリティクラスや関数らが用意されています。

コンポーネント用の基底クラス

これらの基底クラスは、ご自身の拡張にSphinxのコンポーネント (例えば Config, BuildEnvironment など)を容易に取り込むために有用なものです。

注釈

これらのサブクラスは素のdocutilsと共には動作しないかもしれません。これらのクラスはSphinxに強く結びつけられています。

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

Transformsの基底クラス

Compared with docutils.transforms.Transform, this class improves accessibility to Sphinx APIs.

property app: Sphinx

Sphinx オブジェクトへの参照です.

property config: Config

Config オブジェクトへの参照です。

property env: BuildEnvironment

Reference to the BuildEnvironment object.

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

A base class of post-transforms.

Post transforms are invoked to modify the document to restructure it for outputting. They resolve references, convert images, do special transformation for each output formats and so on. This class helps to implement these post transforms.

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

Override to apply the transform to the document tree.

is_supported() → bool[ソース]

Check this transform working for current builder.

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

Main method of post transforms.

Subclasses should override this method instead of apply().

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

Sphinx ディレクティブ用の基底クラス

このクラスにはSphinx ディレクティブ用のヘルパーメソッドが用意されています。

Added in version 1.8.

注釈

これらのサブクラスはdocutilsと共には動作しないかもしれません。これらのクラスはSphinxに強く結びつけられています。

get_location() → str[ソース]

Get current location info for logging.

Added in version 4.2.

get_source_info() → tuple[str | None, int | None][ソース]

Get source and line number.

Added in version 3.0.

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

Parse the directive's content into nodes.

パラメータ:

allow_section_headings -- Are titles (sections) allowed in the directive's content? Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

Added in version 7.4.

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

Parse text as inline elements.

パラメータ:

  • text -- The text to parse, which should be a single line or paragraph. This cannot contain any structural elements (headings, transitions, directives, etc).

  • lineno -- The line number where the interpreted text begins.

戻り値:

A list of nodes (text and inline elements) and a list of system_messages.

Added in version 7.4.

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

Parse text into nodes.

パラメータ:

  • text -- Text, in string form. StringList is also accepted.

  • allow_section_headings -- Are titles (sections) allowed in text? Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of Structural nodes, which includes document, section, and sidebar nodes.

  • offset -- The offset of the content.

Added in version 7.4.

set_source_info(node: Node) → None[ソース]

Set source and line number to the node.

Added in version 2.1.

property config: Config

Config オブジェクトへの参照です。

Added in version 1.8.

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 1.8.

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

A base class for Sphinx roles.

This class provides helper methods for Sphinx roles.

Added in version 2.0.

注釈

これらのサブクラスはdocutilsと共には動作しないかもしれません。これらのクラスはSphinxに強く結びつけられています。

get_location() → str[ソース]

Get current location info for logging.

Added in version 4.2.

property config: Config

Config オブジェクトへの参照です。

Added in version 2.0.

content: Sequence[str]

A list of strings, the directive content for customisation (from the "role" directive).

property env: BuildEnvironment

Reference to the BuildEnvironment object.

Added in version 2.0.

inliner: Inliner

The docutils.parsers.rst.states.Inliner object.

lineno: int

The line number where the interpreted text begins.

name: str

The role name actually used in the document.

options: dict[str, Any]

A dictionary of directive options for customisation (from the "role" directive).

rawtext: str

A string containing the entire interpreted text input.

text: str

The interpreted text content.

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

A base class for reference roles.

The reference roles can accept link title <target> style as a text for the role. The parsed result; link title and target will be stored to self.title and self.target.

Added in version 2.0.

disabled: bool

A boolean indicates the reference is disabled.

has_explicit_title: bool

A boolean indicates the role has explicit title or not.

target: str

The link target for the interpreted text.

title: str

The link title for the interpreted text.

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

画像コンバーター用の基底クラス

An image converter is kind of Docutils transform module. It is used to convert image files which are not supported by a builder to the appropriate format for that builder.

For example, LaTeX builder supports PDF, PNG and JPEG as image formats. However it does not support SVG images. For such case, using image converters allows to embed these unsupported images into the document. One of the image converters; sphinx.ext.imgconverter can convert a SVG image to PNG format using Imagemagick internally.

自分自身のカスタム画像コンバーターを作成するために3つのステップがあります:

  1. ImageConverter クラスのサブクラスを作成します。

  2. conversion_rules, is_available() と convert() をオーバーライドします。

  3. お使いの画像コンバーターを Sphinx.add_post_transform() を使ってSphinxに登録してください。

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

Convert an image file to the expected format.

_from is a path of the source image file, and _to is a path of the destination file.

is_available() → bool[ソース]

当該の画像コンバーターが利用可能かどうかを返します。

available: bool | None = None

The converter is available or not. Will be filled at the first call of the build. The result is shared in the same process.

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

当該の画像コンバーターがサポートする変換規則で、ソースと出力先の画像フォーマット（MIMEタイプ）の組からなるリストで表現されます。

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

Numerical priority of this transform, 0 through 999 (override).

Utility functions

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][ソース]

Parse text into nodes.

パラメータ:

  • state -- The state machine state. Must be a subclass of RSTState.

  • text -- Text, in string form. StringList is also accepted.

  • source -- The text's source, used when creating a new StringList.

  • offset -- The offset of the content.

  • allow_section_headings -- Are titles (sections) allowed in text? Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should only be children of document or section nodes.

  • keep_title_context --

    If this is False (the default), then content is parsed as if it were an independent document, meaning that title decorations (e.g. underlines) do not need to match the surrounding document. This is useful when the parsed content comes from a completely different context, such as docstrings. If this is True, then title underlines must match those in the surrounding document, otherwise the behaviour is undefined.

    Warning: Up to Docutils 0.21, sections with a decoration style matching a level that is higher than the current section level are silently discarded! Since Docutils 0.22.1, an error is reported.

Added in version 7.4.

Utility types

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

The metadata returned by an extension's setup() function.

See 拡張機能のメタデータ.

env_version: int

An integer that identifies the version of env data added by the extension.

parallel_read_safe: bool

Indicate whether parallel reading of source files is supported by the extension.

parallel_write_safe: bool

Indicate whether parallel writing of output files is supported by the extension (default: True).

version: str

The extension version (default: 'unknown version').