网页 综合 更新时间 2026-11-17 02:23:04

Builder API — Sphinx documentation

自动蜘蛛 www.sphinx-doc.org 正文约 2975 字
This is the base class for all builders.
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:
The builder’s name. This is the value used to select builders on the command line.
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.
The message emitted upon successful build completion. This can be a printf-style template string with the following keys: outdir, project
Whether it is safe to make parallel write_doc() calls.
The list of MIME types of image formats supported by the builder. Image files are searched in the order in which they appear here.
The builder can produce output documents that may fetch external images when opened.
The file format produced by the builder allows images to be embedded using data-URIs.
default translator class for the builder. This can be overridden by set_translator().
These methods define the core build workflow and must not be overridden:
Build all source files.
Only rebuild as much as needed for changes in the filenames.
Only rebuild what was changed or added since last build.
Main build method, usually called by a specific build_* method.
First updates the environment, and then calls write().
(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).
Parse a file and add/update inventory entries for the doctree.
Write the doctree to a file, to be used as a cache by re-builds.
Write builder specific output files.
These must be implemented in builder sub-classes:
Return an iterable of output files that are outdated, or a string describing what an update build will build.
If the builder does not output individual files corresponding to source files, return a string here. If it does, return an iterable of those files that need to be written.
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().
Return the target URI for a document name.
typ can be used to qualify the link characteristic for individual builders.
These methods can be overridden in builder sub-classes:
Load necessary templates and perform initialization. The default implementation does nothing.
Write all documents in docnames.
This method can be overridden if a builder does not create output files for each document.
A place where you can add logic before write_doc() is run
Where assets (images, static files, etc) are copied before writing
Return a relative URI between two source filenames.
访问原文 返回搜索 https://www.sphinx-doc.org/en/master/extdev/builderapi.html
本页为82搜索生成的网页快照,内容来自站内索引;演示数据的原文链接仅作示例。