Builder API

class sphinx.builders.Builder

このクラスはすべてのビルダーのベースクラスです。

It follows this basic workflow:

Call graph for the standard Sphinx build workflow

Overridable Attributes

These class attributes should be set on builder sub-classes:

name: ClassVar[str] = ''

The builder's name. This is the value used to select builders on the command line.

format: ClassVar[str] = ''

The builder's output format, or '' if no document output is produced. This is commonly the file extension, e.g. "html", though any string value is accepted. The builder's format string can be used by various components such as SphinxPostTransform or extensions to determine their compatibility with the builder.

epilog: ClassVar[str] = ''

The message emitted upon successful build completion. This can be a printf-style template string with the following keys: outdir, project

allow_parallel: ClassVar[bool] = False

Whether it is safe to make parallel write_doc() calls.

supported_image_types: ClassVar[list[str]] = []

The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.

supported_remote_images: ClassVar[bool] = False

The builder can produce output documents that may fetch external images when opened.

supported_data_uri_images: ClassVar[bool] = False

The file format produced by the builder allows images to be embedded using data-URIs.

default_translator_class: ClassVar[type[nodes.NodeVisitor]]

default translator class for the builder. This can be overridden by set_translator().

Core Methods

These methods define the core build workflow and must not be overridden:

final build_all() → None

すべてのソースファイルをビルドします。

final build_specific(filenames: Sequence[Path]) → None

filenames に含まれる、変更が必要なものだけ再ビルドします。

final build_update() → None

最後のビルドの後に変更されたり、追加されたものだけ再ビルドします。

final build(docnames: Iterable[str] | None, summary: str | None = None, method: Literal['all', 'specific', 'update'] = 'update') → None

Main build method, usually called by a specific build_* method.

First updates the environment, and then calls write().

final read() → list[str]

(Re-)read all files new or changed since last update.

Store all environment docnames in the canonical format (ie using SEP as a separator in place of os.path.sep).

final read_doc(docname: str, *, _cache: bool = True) → None

Parse a file and add/update inventory entries for the doctree.

final write_doctree(docname: str, doctree: document, *, _cache: bool = True) → None

Write the doctree to a file, to be used as a cache by re-builds.

final write(build_docnames: Iterable[str] | None, updated_docnames: Iterable[str], method: Literal['all', 'specific', 'update'] = 'update') → None

Write builder specific output files.

Abstract Methods

These must be implemented in builder sub-classes:

get_outdated_docs() → str | Iterable[str]

ビルドが必要な、古いファイルを返すイテレータを返します。言い換えると、アップデートビルドを行うと、何がビルドされるか、というのを説明する文字列を返します。

もしもビルダーがソースファイルに関連する、個別のファイルを出力しない場合には、ここでは文字列を返してください。その場合には、書かれるべきファイルのイテレータを返します。

write_doc(docname: str, doctree: document) → None

Write the output file for the document

パラメータ:

• docname -- the docname.

• doctree -- defines the content to be written.

The output filename must be determined within this method, typically by calling get_target_uri() or get_relative_uri().

get_target_uri(docname: str, typ: str | None = None) → str

ドキュメント名に関連する、対象のURLを返します。

typ はそれぞれのビルダーごとのリンクの修飾子として使うことができます。

Overridable Methods

These methods can be overridden in builder sub-classes:

init() → None

必要なテンプレートをロードしたり、初期化を行うためのメソッドです。 デフォルトの実装では、何も行いません。

write_documents(docnames: Set[str]) → None

Write all documents in docnames.

This method can be overridden if a builder does not create output files for each document.

prepare_writing(docnames: Set[str]) → None

write_doc() が実行される前に実行したい動作を記述する場所です。

copy_assets() → None

Where assets (images, static files, etc) are copied before writing

get_relative_uri(from_: str, to: str, typ: str | None = None) → str

2つのソースファイル間の相対URIを返します。

Raises:

NoUri if there's no way to return a sensible URI.

finish() → None

ビルドプロセスの終了です。

デフォルトの実装では何も呼び出されません。

Attributes

Attributes that are callable from the builder instance:

events

EventManager オブジェクト。

Overridable Attributes (extensions)

Builder sub-classes can set these attributes to support built-in extensions:

supported_linkcode: str

By default, the linkcode extension will only inject references for an html builder. The supported_linkcode class attribute can be defined in a non-HTML builder to support managing references generated by linkcode. The expected value for this attribute is an expression which is compatible with only.

For example, if a builder was named custom-builder, the following can be used:

class CustomBuilder(Builder):
    supported_linkcode = 'custom-builder'
    ...

Previous

ビルド環境API

Next

Event Manager API