Merge pull request #7904 from choldgraf/events

DOC: Events overview

1 files changed, 34 insertions, 0 deletions

diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst
index d5b1a8a98..036b57ec1 100644
--- a/doc/extdev/appapi.rst
+++ b/doc/extdev/appapi.rst
@@ -157,6 +157,40 @@ connect handlers to the events.  Example:
        app.connect('source-read', source_read_handler)
 
 
+Below is an overview of each event that happens during a build. In the list
+below, we include the event name, its callback parameters, and the input and output
+type for that event::
+
+   1. event.config-inited(app,config)
+   2. event.builder-inited(app)
+   3. event.env-get-outdated(app, env, added, changed, removed)
+   4. event.env-before-read-docs(app, env, docnames)
+
+   for docname in docnames:
+      5.  event.env-purge-doc(app, env, docname)
+      if doc changed and not removed:
+         6. source-read(app, docname, source)
+         7. run source parsers: text -> docutils.document (parsers can be added with the app.add_source_parser() API)
+         8. apply transforms (by priority): docutils.document -> docutils.document
+            - event.doctree-read(app, doctree) is called in the middly of transforms,
+              transforms come before/after this event depending on their priority.
+   9. (if running in parallel mode, for each process) event.env-merged-info(app, env, docnames, other)
+   10. event.env-updated(app, env)
+   11. event.env-get-updated(app, env)
+   11. event.env-check-consistency(app, env)
+
+   # For builders that output a single page, they are first joined into a single doctree before post-transforms/doctree-resolved
+   for docname in docnames:
+      12. apply post-transforms (by priority): docutils.document -> docutils.document
+      13. event.doctree-resolved(app, doctree, docname)
+          - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode)
+
+   14. Generate output files
+
+   15. event.build-finished(app, exception)
+
+Here is a more detailed list of these events.
+
 .. event:: builder-inited (app)
 
    Emitted when the builder object has been created.  It is available as