diff --git a/CHANGES.rst b/CHANGES.rst index 392dfaadf..4d999c79c 100644 --- a/CHANGES.rst +++ b/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 ---------- diff --git a/doc/_static/diagrams/sphinx_core_events_flow.dot b/doc/_static/diagrams/sphinx_core_events_flow.dot index f60076089..1499e6ba8 100644 --- a/doc/_static/diagrams/sphinx_core_events_flow.dot +++ b/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"}; } diff --git a/doc/extdev/event_callbacks.rst b/doc/extdev/event_callbacks.rst index a776491fd..40191c883 100644 --- a/doc/extdev/event_callbacks.rst +++ b/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` diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 9af439f28..076af8af5 100644 --- a/sphinx/builders/__init__.py +++ b/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 diff --git a/sphinx/events.py b/sphinx/events.py index af8dfb4e2..0a8cec277 100644 --- a/sphinx/events.py +++ b/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', }