diff --git a/doc/extdev/event_callbacks.rst b/doc/extdev/event_callbacks.rst index a0c2976f98..1f9ccd2663 100644 --- a/doc/extdev/event_callbacks.rst +++ b/doc/extdev/event_callbacks.rst @@ -24,6 +24,9 @@ to connect functions to the events: and calling them them with :meth:`.EventManager.emit` or :meth:`.EventManager.emit_firstresult`. +Many events pass a :term:`doctree` to their callbacks. +See the glossary entry for where its node types are documented. + Core events overview -------------------- diff --git a/doc/glossary.rst b/doc/glossary.rst index 272bf0fae5..27962aa913 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -35,6 +35,22 @@ Glossary See :ref:`rst-directives` for more information. + doctree + The in-memory representation of a parsed document: a tree of docutils + nodes whose root is a :class:`docutils.nodes.document` instance. + Sphinx creates one doctree for each source file during the reading + phase, and many :ref:`events ` pass a doctree to their callbacks, + which may inspect or modify it in-place. + + Docutils does not provide API documentation for its node classes; + the available node types and their attributes are described in + `The Docutils Document Tree + `__, + and the implementation is in the `docutils.nodes + `__ + module. Nodes added by Sphinx are documented in :ref:`nodes`. + See also :ref:`build-phases`. + document name Since reStructuredText source files can have different extensions (some people like ``.txt``, some like ``.rst`` -- the extension can be