mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
37ff33dff7
This commit: - annotates the `Builder`'s "core" methods, with [`final`](https://docs.python.org/3/library/typing.html#typing.final) - adds a UML graph to the Builder API docs - Adds more methods to the Builder API docs to make it clearer for extension developers, what is expected from a new builder subclass.
113 lines
3.0 KiB
ReStructuredText
113 lines
3.0 KiB
ReStructuredText
.. _writing-builders:
|
|
|
|
Builder API
|
|
===========
|
|
|
|
.. currentmodule:: sphinx.builders
|
|
|
|
.. class:: Builder
|
|
|
|
This is the base class for all builders.
|
|
|
|
It follows this basic workflow:
|
|
|
|
.. graphviz::
|
|
:caption: UML for the standard Sphinx build workflow
|
|
|
|
digraph build {
|
|
graph [
|
|
rankdir=LR
|
|
];
|
|
node [
|
|
shape=rect
|
|
style=rounded
|
|
];
|
|
|
|
"Sphinx" [
|
|
shape=record
|
|
label = "Sphinx | <init> __init__ | <build> build"
|
|
];
|
|
"Sphinx":init -> "Builder.init";
|
|
"Sphinx":build -> "Builder.build_all";
|
|
"Sphinx":build -> "Builder.build_specific";
|
|
"Builder.build_update" [
|
|
shape=record
|
|
label = "<p1> Builder.build_update | Builder.get_outdated_docs"
|
|
];
|
|
"Sphinx":build -> "Builder.build_update":p1 ;
|
|
|
|
"Builder.build_all" -> "Builder.build";
|
|
"Builder.build_specific" -> "Builder.build";
|
|
"Builder.build_update":p1 -> "Builder.build";
|
|
|
|
"Builder.build" -> "Builder.read";
|
|
"Builder.write" [
|
|
shape=record
|
|
label = "<p1> Builder.write | Builder._write_serial | Builder._write_parallel"
|
|
];
|
|
"Builder.build" -> "Builder.write";
|
|
"Builder.build" -> "Builder.finish";
|
|
|
|
"Builder.read" -> "Builder.read_doc";
|
|
"Builder.read_doc" -> "Builder.write_doctree";
|
|
|
|
"Builder.write":p1 -> "Builder.prepare_writing";
|
|
"Builder.write":p1 -> "Builder.copy_assets";
|
|
"Builder.write":p1 -> "Builder.write_doc";
|
|
|
|
"Builder.write_doc" -> "Builder.get_relative_uri";
|
|
|
|
"Builder.get_relative_uri" -> "Builder.get_target_uri";
|
|
}
|
|
|
|
.. rubric:: Overridable Attributes
|
|
|
|
These attributes should be set on builder sub-classes:
|
|
|
|
.. autoattribute:: name
|
|
.. autoattribute:: format
|
|
.. autoattribute:: epilog
|
|
.. autoattribute:: allow_parallel
|
|
.. autoattribute:: supported_image_types
|
|
.. autoattribute:: supported_remote_images
|
|
.. autoattribute:: supported_data_uri_images
|
|
.. autoattribute:: default_translator_class
|
|
|
|
.. rubric:: Core Methods
|
|
|
|
These methods are predefined and should generally not be overridden,
|
|
since they form the core of the build process:
|
|
|
|
.. automethod:: build_all
|
|
.. automethod:: build_specific
|
|
.. automethod:: build_update
|
|
.. automethod:: build
|
|
.. automethod:: read
|
|
.. automethod:: read_doc
|
|
.. automethod:: write_doctree
|
|
|
|
.. rubric:: Overridable Methods
|
|
|
|
These must be implemented in builder sub-classes:
|
|
|
|
.. automethod:: get_outdated_docs
|
|
.. automethod:: prepare_writing
|
|
.. automethod:: write_doc
|
|
.. automethod:: get_target_uri
|
|
|
|
These methods can be overridden in builder sub-classes:
|
|
|
|
.. automethod:: init
|
|
.. automethod:: write
|
|
.. automethod:: copy_assets
|
|
.. automethod:: get_relative_uri
|
|
.. automethod:: finish
|
|
|
|
.. rubric:: Attributes
|
|
|
|
Attributes that are callable from the builder instance:
|
|
|
|
.. attribute:: events
|
|
|
|
An :class:`.EventManager` object.
|