Add a `write-started` event (#12567)

Co-authored-by: Adam Turner <9087854+aa-turner@users.noreply.github.com>

CHANGES.rst

@@ -104,6 +104,8 @@ Features added
   Patch by Adam Turner and David Stansby.
 * #12506 Add ``level`` option to :rst:dir:`rubric` directive.
   Patch by Chris Sewell.
+* #12567: Add the :event:`write-started` event.
+  Patch by Chris Sewell.
 
 Bugs fixed
 ----------

doc/_static/diagrams/sphinx_core_events_flow.dot

@@ -82,6 +82,8 @@ digraph events {
     if_read_changes -> "env-check-consistency";
 
     // during write phase
+    "write-started"[style=filled fillcolor="#D5FFFF" color=blue penwidth=2];
+    "Builder.build":write -> "write-started";
     "Builder.write" [label = "Builder.write()"]
     "Builder.build":write -> "Builder.write";
     write_each_doc [shape="ellipse", label="for updated"];
@@ -118,6 +120,6 @@ digraph events {
     {rank=same; "env-get-outdated" "env-before-read-docs" "env-get-updated"};
     {rank=same; "env-purge-doc" "source-read" "doctree-read", "merge_each_process"};
     {rank=same; "env-updated" "env-check-consistency"};
-    {rank=same; "env-merge-info" "Builder.write"};
+    {rank=same; "env-merge-info" "write-started" "Builder.write"};
     {rank=max; "build-finished"};
 }

doc/extdev/event_callbacks.rst

@@ -52,21 +52,27 @@ Below is an overview of the core event that happens during a build.
 
    10. event.env-updated(app, env)
    11. event.env-get-updated(app, env)
-   12. event.env-check-consistency(app, env)
+
+   if environment is written to disk:
+      12. event.env-check-consistency(app, env)
+
+   13. event.write-started(app, builder)
+       - This is called after ``app.parallel_ok`` has been set,
+         which must not be altered by any event handler.
 
    # The updated-docs list can be builder dependent, but generally includes all new/changed documents,
    # plus any output from `env-get-updated`, and then all "parent" documents in the ToC tree
    # For builders that output a single page, they are first joined into a single doctree before post-transforms
    # or the doctree-resolved event is emitted
    for docname in updated-docs:
-      13. apply post-transforms (by priority): docutils.document -> docutils.document
-      14. event.doctree-resolved(app, doctree, docname)
+      14. apply post-transforms (by priority): docutils.document -> docutils.document
+      15. event.doctree-resolved(app, doctree, docname)
           - In the event that any reference nodes fail to resolve, the following may emit:
           - event.missing-reference(env, node, contnode)
           - event.warn-missing-reference(domain, node)
 
-   15. Generate output files
-   16. event.build-finished(app, exception)
+   16. Generate output files
+   17. event.build-finished(app, exception)
 
 Here is also a flow diagram of the events,
 within the context of the Sphinx build process:
@@ -322,6 +328,16 @@ Here is a more detailed list of these events.
 
    .. versionadded:: 1.6
 
+.. event:: write-started (app, builder)
+
+   :param app: :class:`.Sphinx`
+   :param builder: :class:`.Builder`
+
+   Emitted before the builder starts to
+   resolve and write documents.
+
+   .. versionadded:: 7.4
+
 .. event:: build-finished (app, exception)
 
    :param app: :class:`.Sphinx`

sphinx/builders/__init__.py

@@ -579,6 +579,9 @@ class Builder:
         method: Literal['all', 'specific', 'update'] = 'update',
     ) -> None:
         """Write builder specific output files."""
+        # Allow any extensions to perform setup for writing
+        self.events.emit('write-started', self)
+
         if build_docnames is None or build_docnames == ['__all__']:
             # build_all
             build_docnames = self.env.found_docs

sphinx/events.py

@@ -45,6 +45,7 @@ core_events = {
     'warn-missing-reference': 'domain, node',
     'doctree-resolved': 'doctree, docname',
     'env-updated': 'env',
+    'write-started': 'builder',
     'build-finished': 'exception',
 }