Builder API¶
Todo
Expand this.
- class sphinx.builders.Builder[source]¶
This is the base class for all builders.
These attributes should be set on builder classes:
-
name =
''
¶ The builder’s name, for the -b command line option.
-
format =
''
¶ The builder’s output format, or ‘’ if no document output is produced.
-
epilog =
''
¶ The message emitted upon successful build completion. This can be a printf-style template string with the following keys:
outdir
,project
-
allow_parallel =
False
¶ allow parallel write_doc() calls
-
supported_image_types : 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 =
False
¶ The builder supports remote images or not.
-
supported_data_uri_images =
False
¶ The builder supports data URIs or not.
-
default_translator_class : type[NodeVisitor] =
None
¶ default translator class for the builder. This can be overridden by
app.set_translator()
.
These methods are predefined and will be called from the application:
-
get_relative_uri(from_: str, to: str, typ: str | None =
None
) str [source]¶ Return a relative URI between two source filenames.
May raise environment.NoUri if there’s no way to return a sensible URI.
- build_specific(filenames: list[str]) None [source]¶
Only rebuild as much as needed for changes in the filenames.
-
build(docnames: Iterable[str], summary: str | None =
None
, method: str ='update'
) None [source]¶ Main build method.
First updates the environment, and then calls
write()
.
These methods can be overridden in concrete builder classes:
- init() None [source]¶
Load necessary templates and perform initialization. The default implementation does nothing.
- get_outdated_docs() str, Iterable[str] [source]¶
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.
-
get_target_uri(docname: str, typ: str | None =
None
) str [source]¶ Return the target URI for a document name.
typ can be used to qualify the link characteristic for individual builders.
- prepare_writing(docnames: set[str]) None [source]¶
A place where you can add logic before
write_doc()
is run
- write_doc(docname: str, doctree: document) None [source]¶
Where you actually write something to the filesystem.
Attributes
- events¶
An
EventManager
object.
-
name =