Merging upstream version 7.4.7.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 29 insertions, 9 deletions

diff --git a/doc/extdev/builderapi.rst b/doc/extdev/builderapi.rst
index 5c5a525..9259aaa 100644
--- a/doc/extdev/builderapi.rst
+++ b/doc/extdev/builderapi.rst
@@ -3,15 +3,20 @@
 Builder API
 ===========
 
-.. todo:: Expand this.
-
 .. currentmodule:: sphinx.builders
 
 .. class:: Builder
 
    This is the base class for all builders.
 
-   These attributes should be set on builder classes:
+   It follows this basic workflow:
+
+   .. graphviz:: /_static/diagrams/sphinx_build_flow.dot
+      :caption: UML for the standard Sphinx build workflow
+
+   .. rubric:: Overridable Attributes
+
+   These attributes should be set on builder sub-classes:
 
    .. autoattribute:: name
    .. autoattribute:: format
@@ -22,24 +27,39 @@ Builder API
    .. autoattribute:: supported_data_uri_images
    .. autoattribute:: default_translator_class
 
-   These methods are predefined and will be called from the application:
+   .. rubric:: Core Methods
+
+   These methods are predefined and should generally not be overridden,
+   since they form the core of the build process:
 
-   .. automethod:: get_relative_uri
    .. automethod:: build_all
    .. automethod:: build_specific
    .. automethod:: build_update
    .. automethod:: build
+   .. automethod:: read
+   .. automethod:: read_doc
+   .. automethod:: write_doctree
 
-   These methods can be overridden in concrete builder classes:
+   .. rubric:: Overridable Methods
+
+   These must be implemented in builder sub-classes:
 
-   .. automethod:: init
    .. automethod:: get_outdated_docs
-   .. automethod:: get_target_uri
    .. 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
 
-   **Attributes**
+   .. rubric:: Attributes
+
+   Attributes that are callable from the builder instance:
 
    .. attribute:: events