ユーティリティ¶
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 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.
- class sphinx.util.docutils.SphinxDirective(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine)[ソース]¶
Sphinx ディレクティブ用の基底クラス
このクラスにはSphinx ディレクティブ用のヘルパーメソッドが用意されています。
注釈
これらのサブクラスはdocutilsと共には動作しないかもしれません。これらのクラスはSphinxに強く結びつけられています。
- property env: BuildEnvironment¶
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に強く結びつけられています。
- content: Sequence[str]¶
A list of strings, the directive content for customisation (from the "role" directive).
- property env: BuildEnvironment¶
Reference to the
BuildEnvironment
object.
- inliner: Inliner¶
The
docutils.parsers.rst.states.Inliner
object.
- 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 toself.title
andself.target
.
- class sphinx.transforms.post_transforms.images.ImageConverter(*args: Any, **kwargs: Any)[ソース]¶
画像コンバーター用の基底クラス
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つのステップがあります:
ImageConverter
クラスのサブクラスを作成します。conversion_rules
,is_available()
と ``convert()``をオーバーライドします。お使いの画像コンバーターを:py:meth:.Sphinx.add_post_transform を使ってSphinxに登録してください。
- convert(_from: str, _to: 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.
- 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.
課題
This should be refactored not to store the state without class variable.
- 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 components¶
Utility types¶
- class sphinx.util.typing.ExtensionMetadata[ソース]¶
The metadata returned by an extension's
setup()
function.See 拡張機能のメタデータ.
- parallel_read_safe: bool¶
Indicate whether parallel reading of source files is supported by the extension.