ユーティリティ

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 オブジェクトへの参照です.

property config

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

property env

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 do resolving references, convert images, special transformation for each output formats and so on. This class helps to implement these post transforms.

apply(**kwargs)[ソース]

Override to apply the transform to the document tree.

is_supported()[ソース]

Check this transform working for current builder.

run(**kwargs)[ソース]

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 ディレクティブ用のヘルパーメソッドが用意されています。

注釈

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

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

Set source and line number to the node.

property config

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

property env

Reference to the BuildEnvironment object.

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

A base class for Sphinx roles.

This class provides helper methods for Sphinx roles.

注釈

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

property config

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

content = None

A list of strings, the directive content for customization

property env

Reference to the BuildEnvironment object.

inliner = None

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

lineno = None

The line number where the interpreted text begins.

name = None

The role name actually used in the document.

options = None

A dictionary of directive options for customization

rawtext = None

A string containing the entire interpreted text input.

text = None

The interpreted text content.

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

A base class for reference roles.

The reference roles can accpet 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.

has_explicit_title = None

A boolean indicates the role has explicit title or not.

target = None

The link target for the interpreted text.

title = None

The link title for the interpreted text.

class sphinx.transforms.post_transforms.images.ImageConverter(*args, **kwargs)[ソース]

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

画像コンバーターは Docutils の変換モジュールの一種です。ビルダーでサポートされていない画像ファイルを、当該ビルダーに適切なフォーマットに変換する際に用いられます。

例えば、LaTeX ビルダー はPDF、PNGとJPEGを画像フォーマットをサポートしています。しかし、SVG画像をサポートしていません。このような場合、画像コンバーターはサポートされていない画像らをドキュメントに埋め込むことを許可します。画像コンバーターの一つである sphinx.ext.imgconverter は、内部でImagemagick を用いてSVG画像からPNG形式への変換を可能にしています。

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

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

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

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

convert(_from, _to)[ソース]

画像ファイルを期待されるフォーマットに変換します。

_from はソースの画像ファイルがあるパスで、_to は出力ファイルのパスになります。

is_available()[ソース]

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

conversion_rules = []

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

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

Utility components

class sphinx.events.EventManager(app=None)[ソース]

Event manager for Sphinx.

add(name)[ソース]

Register a custom Sphinx event.

connect(name, callback)[ソース]

Connect a handler to specific event.

disconnect(listener_id)[ソース]

Disconnect a handler.

emit(name, *args)[ソース]

Emit a Sphinx event.

emit_firstresult(name, *args)[ソース]

Emit a Sphinx event and returns first result.

This returns the result of the first handler that doesn't return None.