From 853060a64673453d53259d5537ea21ee2a0ee136 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 2 Jul 2020 13:42:53 -0700 Subject: [PATCH 1/2] events --- doc/extdev/appapi.rst | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index d5b1a8a982e..cd7205cd078 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. call builder + + 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 From ef03bcc6ea47d83132b54c4b3894990c086af5b9 Mon Sep 17 00:00:00 2001 From: Chris Holdgraf Date: Thu, 2 Jul 2020 13:46:44 -0700 Subject: [PATCH 2/2] output files comment --- doc/extdev/appapi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/extdev/appapi.rst b/doc/extdev/appapi.rst index cd7205cd078..036b57ec10f 100644 --- a/doc/extdev/appapi.rst +++ b/doc/extdev/appapi.rst @@ -185,7 +185,7 @@ type for that event:: 13. event.doctree-resolved(app, doctree, docname) - (for any reference node that fails to resolve) event.missing-reference(env, node, contnode) - 14. call builder + 14. Generate output files 15. event.build-finished(app, exception)