Skip to content

DOC: Events overview #7904

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jul 3, 2020
Merged

DOC: Events overview #7904

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
853060a
events
choldgraf Jul 2, 2020
ef03bcc
output files comment
choldgraf Jul 2, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 34 additions & 0 deletions doc/extdev/appapi.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down